head_music 17.4.0 → 17.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4d075fb623ea50351c7ac422f44be04c265867253312b6b27faffaf76bb3b397
-  data.tar.gz: 5649553e987c0a98cd9388d24d6e15155f88da4e59eaf62f7a2d9f988e656b36
+  metadata.gz: 5a439a4b39c708eb38984b3878e7bc0c02ce92d7c693d34041ed3b8c69acfffe
+  data.tar.gz: d0b702f38b7de8826fe7a345c3b17d0a8ea8c963bd922343889ba97a47f3538e
 SHA512:
-  metadata.gz: a89a0dfc44c68e823e5c1eff6c48b950b759cdd059c504adacd8bd6b3d06dc0b23bc1a13b690e68086526a33ab3bebc1617825abecfc3ab108c89425a44d6f55
-  data.tar.gz: 921ce718ccc4b728ed57dce347fbce73ae7c120960931b32933a5893f52992b4aa40ec115e248421a3f53d3a66defff0b4d7eac15efaf34ae51fae23e5e2a328
+  metadata.gz: 266406dca2449e15a0d72e4ac315190929aa048d18c6236f07d5eea23d5b220dcc037408edb7f5a2a508e677dee5bbf70bb96b620e1bcdcf75df145623efff9e
+  data.tar.gz: 81fcf78c8ec6234b1478d0c6ca92acdc096bb714de76e33d1bd19bf21e52fce8c0b3831fa72b2e8ec2cbe4dad21d399886cd0e62c416934fd6778ab08d03308d

data/.github/workflows/ci.yml

@@ -16,7 +16,7 @@ jobs:
         activesupport-version: ['7.2', '8.0']
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v5
 
     - name: Set up Ruby ${{ matrix.ruby-version }}
       uses: ruby/setup-ruby@v1
@@ -43,7 +43,7 @@ jobs:
   lint:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v5
 
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1
@@ -57,7 +57,7 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v5
 
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1

data/.github/workflows/release.yml

@@ -13,7 +13,7 @@ jobs:
       id-token: write
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v5
 
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1

data/.github/workflows/security.yml

@@ -8,13 +8,14 @@ on:
   schedule:
     # Run security checks daily at 9 AM UTC
     - cron: '0 9 * * *'
+  workflow_dispatch:
 
 jobs:
   security:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v5
 
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1

data/.rubocop.yml

@@ -31,6 +31,12 @@ RSpec/ContextWording:
 RSpec/MultipleExpectations:
   Enabled: false
 
+# Several data-driven specs build examples from collections resolved at
+# definition time (e.g. `legacy.each`, `melodic_guides.each`), which requires
+# those values to live as locals in the example-group scope.
+RSpec/LeakyLocalVariable:
+  Enabled: false
+
 RSpec/NestedGroups:
   Max: 5
 

data/CHANGELOG.md

@@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [17.5.0] - 2026-07-21
+
+### Added
+
+- Sung text (lyrics) can be attached to the notes of a voice. `HeadMusic::Content::Placement#sing(text, verse:, hyphen_after:)` assigns a syllable to a placement, keyed by verse so a note carries at most one syllable per verse and any number of verses (`glo` on verse 1, `peace` on verse 2 of the same note). A new immutable `HeadMusic::Content::Syllable` value object stores only the minimal linguistic fact — `text`, `verse`, and a `hyphen_after` boolean marking that the word continues onto the next sung note; the MusicXML `syllabic` value (`single`/`begin`/`middle`/`end`) is derived at render time rather than stored, and a melisma is represented by the absence of a syllable on the held notes rather than a stored flag. Syllables serialize through `Placement#to_h` and round-trip through the composition hash deserializer, validated at the import boundary by `Composition::SchemaValues` (non-empty text, a positive-integer verse, and no duplicate verse per placement).
+- The MusicXML writer emits a `<lyric number="N">` element as the last child of each `<note>`, on the lead note of a chord only and the attack of a tied chain only, deriving `<syllabic>` from the `hyphen_after` booleans of the syllable and its predecessor in the same verse and XML-escaping the text. Held notes of a melisma carry no `<lyric>`, matching MusicXML's continuation-by-absence. ABC `w:` lyric-line input and the MusicXML `<extend/>` melisma line remain out of scope for a future release.
+
 ## [17.4.0] - 2026-07-20
 
 ### Changed

data/Gemfile.lock

@@ -1,9 +1,9 @@
 PATH
   remote: .
   specs:
-    head_music (17.4.0)
+    head_music (17.5.0)
       activesupport (>= 7.0, < 10)
-      humanize (~> 2.0)
+      humanize (>= 2, < 4)
       i18n (~> 1.8)
 
 GEM
@@ -30,98 +30,100 @@ GEM
       ice_nine (~> 0.11.0)
       thread_safe (~> 0.3, >= 0.3.1)
     base64 (0.3.0)
-    bigdecimal (3.2.2)
-    bundler-audit (0.9.2)
-      bundler (>= 1.2.0, < 3)
+    bigdecimal (4.1.2)
+    bundler-audit (0.9.3)
+      bundler (>= 1.2.0)
       thor (~> 1.0)
     childprocess (5.1.0)
       logger (~> 1.5)
     coercible (1.0.0)
       descendants_tracker (~> 0.0.1)
-    concurrent-ruby (1.3.7)
-    connection_pool (2.5.3)
+    concurrent-ruby (1.3.8)
+    connection_pool (3.0.2)
     descendants_tracker (0.0.4)
       thread_safe (~> 0.3, >= 0.3.1)
     diff-lcs (1.6.2)
-    docile (1.4.1)
     drb (2.2.3)
-    dry-configurable (1.3.0)
-      dry-core (~> 1.1)
+    dry-configurable (1.4.0)
+      dry-core (~> 1.0)
       zeitwerk (~> 2.6)
-    dry-core (1.1.0)
+    dry-core (1.2.0)
       concurrent-ruby (~> 1.0)
       logger
       zeitwerk (~> 2.6)
-    dry-inflector (1.2.0)
+    dry-inflector (1.3.1)
     dry-initializer (3.2.0)
     dry-logic (1.6.0)
       bigdecimal
       concurrent-ruby (~> 1.0)
       dry-core (~> 1.1)
       zeitwerk (~> 2.6)
-    dry-schema (1.14.1)
+    dry-schema (1.16.0)
       concurrent-ruby (~> 1.0)
       dry-configurable (~> 1.0, >= 1.0.1)
       dry-core (~> 1.1)
       dry-initializer (~> 3.2)
-      dry-logic (~> 1.5)
-      dry-types (~> 1.8)
+      dry-logic (~> 1.6)
+      dry-types (~> 1.9, >= 1.9.1)
       zeitwerk (~> 2.6)
-    dry-types (1.8.3)
-      bigdecimal (~> 3.0)
+    dry-types (1.9.1)
+      bigdecimal (>= 3.0)
       concurrent-ruby (~> 1.0)
       dry-core (~> 1.0)
       dry-inflector (~> 1.0)
       dry-logic (~> 1.4)
       zeitwerk (~> 2.6)
     erubi (1.13.1)
-    flay (2.13.3)
+    flay (2.14.4)
       erubi (~> 1.10)
-      path_expander (~> 1.0)
-      ruby_parser (~> 3.0)
+      path_expander (~> 2.0)
+      prism (~> 1.7)
       sexp_processor (~> 4.0)
-    flog (4.8.0)
-      path_expander (~> 1.0)
-      ruby_parser (~> 3.1, > 3.1.0)
+    flog (4.9.4)
+      path_expander (~> 2.0)
+      prism (~> 1.7)
       sexp_processor (~> 4.8)
-    humanize (2.5.1)
-    i18n (1.14.7)
+    humanize (3.1.0)
+    i18n (1.15.2)
       concurrent-ruby (~> 1.0)
     ice_nine (0.11.2)
     json (2.21.1)
-    kramdown (2.5.1)
-      rexml (>= 3.3.9)
-    language_server-protocol (3.17.0.5)
+    kramdown (2.5.2)
+      rexml (>= 3.4.4)
+    language_server-protocol (3.17.0.6)
     launchy (3.1.1)
       addressable (~> 2.8)
       childprocess (~> 5.0)
       logger (~> 1.6)
     lint_roller (1.1.0)
     logger (1.7.0)
-    minitest (5.25.5)
-    parallel (1.27.0)
-    parser (3.3.9.0)
+    minitest (6.0.6)
+      drb (~> 2.0)
+      prism (~> 1.5)
+    ostruct (0.6.3)
+    parallel (2.1.0)
+    parser (3.3.12.0)
       ast (~> 2.4.1)
       racc
-    path_expander (1.1.3)
-    prism (1.4.0)
-    public_suffix (6.0.2)
+    path_expander (2.0.1)
+    prism (1.9.0)
+    public_suffix (7.0.5)
     racc (1.8.1)
     rainbow (3.1.1)
-    rake (13.3.0)
+    rake (13.4.2)
     reek (6.5.0)
       dry-schema (~> 1.13)
       logger (~> 1.6)
       parser (~> 3.3.0)
       rainbow (>= 2.0, < 4.0)
       rexml (~> 3.1)
-    regexp_parser (2.10.0)
+    regexp_parser (2.12.0)
     rexml (3.4.4)
-    rspec (3.13.1)
+    rspec (3.13.2)
       rspec-core (~> 3.13.0)
       rspec-expectations (~> 3.13.0)
       rspec-mocks (~> 3.13.0)
-    rspec-core (3.13.5)
+    rspec-core (3.13.6)
       rspec-support (~> 3.13.0)
     rspec-expectations (3.13.5)
       diff-lcs (>= 1.2.0, < 2.0)
@@ -129,43 +131,46 @@ GEM
     rspec-its (2.0.0)
       rspec-core (>= 3.13.0)
       rspec-expectations (>= 3.13.0)
-    rspec-mocks (3.13.5)
+    rspec-mocks (3.13.8)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
-    rspec-support (3.13.4)
-    rubocop (1.75.8)
+    rspec-support (3.13.7)
+    rubocop (1.88.2)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
-      parallel (~> 1.10)
+      parallel (>= 1.10)
       parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 2.9.3, < 3.0)
-      rubocop-ast (>= 1.44.0, < 2.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
-    rubocop-ast (1.46.0)
+    rubocop-ast (1.50.0)
       parser (>= 3.3.7.2)
-      prism (~> 1.4)
-    rubocop-performance (1.25.0)
+      prism (~> 1.7)
+    rubocop-performance (1.26.1)
       lint_roller (~> 1.1)
       rubocop (>= 1.75.0, < 2.0)
-      rubocop-ast (>= 1.38.0, < 2.0)
+      rubocop-ast (>= 1.47.1, < 2.0)
     rubocop-rake (0.7.1)
       lint_roller (~> 1.1)
       rubocop (>= 1.72.1)
-    rubocop-rspec (3.6.0)
+    rubocop-rspec (3.10.2)
       lint_roller (~> 1.1)
-      rubocop (~> 1.72, >= 1.72.1)
+      regexp_parser (>= 2.0)
+      rubocop (~> 1.86, >= 1.86.2)
     ruby-progressbar (1.13.0)
-    ruby_parser (3.21.1)
+    ruby_parser (3.22.0)
       racc (~> 1.5)
       sexp_processor (~> 4.16)
-    rubycritic (4.11.0)
+    rubycritic (5.0.0)
       flay (~> 2.13)
       flog (~> 4.7)
       launchy (>= 2.5.2)
+      ostruct
       parser (>= 3.3.0.5)
+      prism (>= 1.6.0)
       rainbow (~> 3.1.1)
       reek (~> 6.5.0, < 7.0)
       rexml
@@ -174,40 +179,35 @@ GEM
       tty-which (~> 0.5.0)
       virtus (~> 2.0)
     securerandom (0.4.1)
-    sexp_processor (4.17.4)
-    simplecov (0.22.0)
-      docile (~> 1.1)
-      simplecov-html (~> 0.11)
-      simplecov_json_formatter (~> 0.1)
-    simplecov-html (0.13.2)
-    simplecov_json_formatter (0.1.4)
-    standard (1.50.0)
+    sexp_processor (4.17.5)
+    simplecov (1.0.2)
+    standard (1.56.0)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.0)
-      rubocop (~> 1.75.5)
+      rubocop (~> 1.88.0)
       standard-custom (~> 1.0.0)
       standard-performance (~> 1.8)
     standard-custom (1.0.2)
       lint_roller (~> 1.0)
       rubocop (~> 1.50)
-    standard-performance (1.8.0)
+    standard-performance (1.9.0)
       lint_roller (~> 1.1)
-      rubocop-performance (~> 1.25.0)
-    thor (1.4.0)
+      rubocop-performance (~> 1.26.0)
+    thor (1.5.0)
     thread_safe (0.3.6)
     tty-which (0.5.0)
     tzinfo (2.0.6)
       concurrent-ruby (~> 1.0)
-    unicode-display_width (3.1.4)
-      unicode-emoji (~> 4.0, >= 4.0.4)
-    unicode-emoji (4.0.4)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
     uri (1.1.1)
     virtus (2.0.0)
       axiom-types (~> 0.1)
       coercible (~> 1.0)
       descendants_tracker (~> 0.0, >= 0.0.3)
-    yard (0.9.44)
-    zeitwerk (2.7.3)
+    yard (0.9.45)
+    zeitwerk (2.8.2)
 
 PLATFORMS
   arm64-darwin-22

data/head_music.gemspec

@@ -33,7 +33,7 @@ Gem::Specification.new do |spec|
   spec.required_ruby_version = ">= 3.3.0"
 
   spec.add_runtime_dependency "activesupport", ">= 7.0", "< 10"
-  spec.add_runtime_dependency "humanize", "~> 2.0"
+  spec.add_runtime_dependency "humanize", ">= 2", "< 4"
   spec.add_runtime_dependency "i18n", "~> 1.8"
 
   spec.add_development_dependency "rake", "~> 13.0"

data/lib/head_music/analysis/pitch_collection.rb

@@ -82,11 +82,11 @@ class HeadMusic::Analysis::PitchCollection
   end
 
   def inspect
-    pitches.map(&:to_s).join(" ")
+    pitches.join(" ")
   end
 
   def to_s
-    pitches.map(&:to_s).join(" ")
+    pitches.join(" ")
   end
 
   def ==(other)

data/lib/head_music/content/composition/hash_deserializer.rb

@@ -78,6 +78,9 @@ class HeadMusic::Content::Composition
           sounds = values.placement_sounds(placement_hash, path)
           placement = voice.place(position, rhythmic_value, sounds)
           placement.beam_break_before = placement_hash["beam_break_before"] if placement_hash.key?("beam_break_before")
+          values.placement_syllables(placement_hash, path).each do |syllable|
+            placement.sing(syllable.text, verse: syllable.verse, hyphen_after: syllable.hyphen_after)
+          end
         end
       end
     end

data/lib/head_music/content/composition/schema_values.rb

@@ -71,6 +71,25 @@ class HeadMusic::Content::Composition
       end
     end
 
+    # "syllables" is an optional array of sung-text data, one entry per verse.
+    # Each entry is a {"text" => ..., "verse" => ..., "hyphen_after" => ...}
+    # hash; verse defaults to 1. Text must be a non-empty string, verse a
+    # positive integer, and no two entries may share a verse (a placement holds
+    # at most one syllable per verse).
+    def placement_syllables(placement_hash, path)
+      values = placement_hash["syllables"]
+      return [] if values.nil?
+
+      unless values.is_a?(Array)
+        raise ArgumentError, "#{path}: syllables must be an Array, got #{values.inspect}"
+      end
+
+      seen_verses = []
+      values.each_with_index.map do |value, index|
+        syllable(value, seen_verses, "#{path}.syllables[#{index}]")
+      end
+    end
+
     def bar_number(bar_hash, index)
       number = bar_hash["number"]
       unless number.is_a?(Integer) && number >= 0
@@ -101,6 +120,27 @@ class HeadMusic::Content::Composition
       pitch
     end
 
+    def syllable(value, seen_verses, path)
+      unless value.is_a?(Hash)
+        raise ArgumentError, "#{path}: syllable must be a Hash, got #{value.inspect}"
+      end
+
+      text = value["text"]
+      unless text.is_a?(String) && !text.empty?
+        raise ArgumentError, "#{path}: syllable text must be a non-empty String, got #{text.inspect}"
+      end
+
+      verse = value.fetch("verse", 1)
+      unless verse.is_a?(Integer) && verse.positive?
+        raise ArgumentError, "#{path}: verse must be a positive Integer, got #{verse.inspect}"
+      end
+
+      raise ArgumentError, "#{path}: duplicate verse #{verse}" if seen_verses.include?(verse)
+      seen_verses << verse
+
+      HeadMusic::Content::Syllable.from_h(value)
+    end
+
     def sound(value, path)
       return pitch(value, path) if value.is_a?(String)
       return unpitched_sound(value, path) if value.is_a?(Hash)

data/lib/head_music/content/placement.rb

@@ -25,6 +25,32 @@ class HeadMusic::Content::Placement
     sounds.select(&:pitched?)
   end
 
+  # Authored sung text: at most one Syllable per verse, keyed by verse number.
+  # Empty for un-texted placements and rests. Set after construction, like
+  # beam_break_before. The MusicXML writer derives <syllabic> from these plus
+  # neighboring placements; melisma is the absence of a syllable here.
+  def syllables
+    @syllables ||= {}
+  end
+
+  # Assigns the syllable for a verse (default verse 1). Returns self so calls
+  # chain across verses. Keys by the Syllable's coerced verse (not the raw
+  # argument) so syllable(2) finds what sing(verse: "2") stored and mixed-type
+  # keys never make syllables.keys.sort raise.
+  def sing(text, verse: 1, hyphen_after: false)
+    syllable = HeadMusic::Content::Syllable.new(text, verse: verse, hyphen_after: hyphen_after)
+    syllables[syllable.verse] = syllable
+    self
+  end
+
+  def syllable(verse = 1)
+    syllables[verse]
+  end
+
+  def sung?
+    syllables.any?
+  end
+
   # The top pitch of a chord (or the only pitch of a note), which melodic
   # analysis treats as the melody note. Returns nil for rests and
   # unpitched-only placements; pitched? is the guard. Enharmonic ties
@@ -64,7 +90,9 @@ class HeadMusic::Content::Placement
 
   # Voice#place merges a same-position placement into the existing one, so a
   # position holds at most one placement. The sound union keeps the chord free
-  # of duplicates, making repeated placement of a sound idempotent.
+  # of duplicates, making repeated placement of a sound idempotent. Syllables
+  # are left untouched: a chord sings one syllable per verse, and the receiver
+  # (the placement already at this position) keeps its own.
   def merge(other)
     unless rhythmic_value == other.rhythmic_value
       raise ArgumentError,
@@ -98,6 +126,7 @@ class HeadMusic::Content::Placement
       "sounds" => sounds.map { |sound| sound_datum(sound) }
     }
     hash["beam_break_before"] = beam_break_before unless beam_break_before.nil?
+    hash["syllables"] = syllables.keys.sort.map { |verse| syllables[verse].to_h } unless syllables.empty?
     hash
   end
 

data/lib/head_music/content/syllable.rb

@@ -0,0 +1,38 @@
+# A module for musical content
+module HeadMusic::Content; end
+
+# A sung syllable attached to a Placement for one verse. Only the minimal
+# linguistic fact is stored: the text, its verse number, and whether the word
+# continues onto the next sung note (hyphen_after). The MusicXML `syllabic`
+# value (single/begin/middle/end) is derived from these at render time rather
+# than stored, and melisma is represented by the absence of a syllable on the
+# following placements, so nothing here encodes it.
+class HeadMusic::Content::Syllable
+  attr_reader :text, :verse, :hyphen_after
+
+  def initialize(text, verse: 1, hyphen_after: false)
+    @text = text.to_s
+    @verse = Integer(verse)
+    @hyphen_after = !!hyphen_after
+    freeze
+  end
+
+  def hyphen_after?
+    hyphen_after
+  end
+
+  def to_h
+    hash = {"text" => text}
+    hash["verse"] = verse unless verse == 1
+    hash["hyphen_after"] = true if hyphen_after
+    hash
+  end
+
+  def self.from_h(hash)
+    new(hash["text"], verse: hash.fetch("verse", 1), hyphen_after: hash.fetch("hyphen_after", false))
+  end
+
+  def ==(other)
+    other.is_a?(self.class) && to_h == other.to_h
+  end
+end

data/lib/head_music/content/voice.rb

@@ -157,6 +157,6 @@ class HeadMusic::Content::Voice
   end
 
   def pitches_string
-    pitches.first(10).map(&:to_s).join(" ")
+    pitches.first(10).join(" ")
   end
 end

data/lib/head_music/notation/music_xml/beam_grouper.rb

@@ -5,7 +5,7 @@ module HeadMusic::Notation::MusicXML
   # the Event list and turns the returned Beams into XML.
   class BeamGrouper
     # A single <beam number="N">type</beam> annotation.
-    Beam = Struct.new(:number, :type, keyword_init: true)
+    Beam = Struct.new(:number, :type)
 
     # One notehead's beaming inputs.
     # - levels: beams this notehead carries alone (eighth=1, sixteenth=2, ...);
@@ -13,7 +13,7 @@ module HeadMusic::Notation::MusicXML
     # - onset: integer offset from the start of the bar, in MusicXML divisions.
     # - beam_break_before: tri-state override vs. the previous event
     #   (nil = meter default, true = force break, false = force join).
-    Event = Struct.new(:levels, :onset, :beam_break_before, keyword_init: true)
+    Event = Struct.new(:levels, :onset, :beam_break_before)
 
     def self.annotate(events, group_unit_divisions)
       new(events, group_unit_divisions).annotate

data/lib/head_music/notation/music_xml/duration_writer.rb

@@ -4,7 +4,7 @@ module HeadMusic::Notation::MusicXML
   # <type>, dot count, and tie flags MusicXML needs for each link of a
   # tied chain. A value with no tied chain yields a single component.
   class DurationWriter
-    Component = Struct.new(:duration, :type, :dots, :tie_start, :tie_stop, keyword_init: true)
+    Component = Struct.new(:duration, :type, :dots, :tie_start, :tie_stop)
 
     # MusicXML's <type> element uses these fixed names rather than the
     # gem's American duration names.

data/lib/head_music/notation/music_xml/writer.rb

@@ -229,10 +229,56 @@ module HeadMusic::Notation::MusicXML
         *Array.new(component.dots) { "#{INDENT * 4}<dot/>" },
         *beam_lines(beams),
         *notation_lines(placement, component),
+        *lyric_lines(placement, component, chord: chord),
         "#{INDENT * 3}</note>"
       ]
     end
 
+    # <lyric> is the last child of <note>. Sung text rides only the lead note
+    # of a chord and only the attack of a tied chain (a tie_stop component is a
+    # continuation, sung once at the start). Held notes of a melisma carry no
+    # syllable and so emit nothing, matching MusicXML's continuation-by-absence.
+    def lyric_lines(placement, component, chord:)
+      return [] if chord || placement.rest? || component.tie_stop
+
+      placement.syllables.keys.sort.flat_map do |verse|
+        syllable = placement.syllables[verse]
+        [
+          %(#{INDENT * 4}<lyric number="#{verse}">),
+          "#{INDENT * 5}<syllabic>#{syllabic(placement, syllable)}</syllabic>",
+          "#{INDENT * 5}<text>#{escape(syllable.text)}</text>",
+          "#{INDENT * 4}</lyric>"
+        ]
+      end
+    end
+
+    # Derives MusicXML's single/begin/middle/end from our stored hyphen_after
+    # booleans: this syllable's, and the previous sung note's for the same verse.
+    def syllabic(placement, syllable)
+      from_previous = previous_syllable(placement, syllable.verse)&.hyphen_after?
+      if from_previous
+        syllable.hyphen_after? ? "middle" : "end"
+      else
+        syllable.hyphen_after? ? "begin" : "single"
+      end
+    end
+
+    # The syllable on the nearest earlier placement in the same voice carrying
+    # text for this verse. Placements are position-sorted, and melisma gaps are
+    # skipped because only sung placements are collected. Array#index compares
+    # with ==, which on Placement is position-only, but a voice holds at most
+    # one placement per position (Voice#insert_into_placements), so that still
+    # locates this exact placement.
+    def previous_syllable(placement, verse)
+      @sung_placements ||= {}
+      sung = @sung_placements[[placement.voice, verse]] ||=
+        placement.voice.placements.select { |candidate| candidate.syllable(verse) }
+      index = sung.index(placement)
+      return nil if index.nil? || index.zero?
+
+      sung[index - 1].syllable(verse)
+    end
+
     def beam_lines(beams)
       beams.map { |beam| %(#{INDENT * 4}<beam number="#{beam.number}">#{beam.type}</beam>) }
     end

data/lib/head_music/style/guidelines/notes_same_length.rb

@@ -54,7 +54,7 @@ class HeadMusic::Style::Guidelines::NotesSameLength < HeadMusic::Style::Annotati
   end
 
   def occurrences_by_rhythmic_value
-    rhythmic_values.each_with_object(Hash.new(0)) { |value, hash| hash[value] += 1 }
+    rhythmic_values.tally
   end
 
   def rhythmic_values

data/lib/head_music/time/musical_position.rb

@@ -39,6 +39,7 @@ module HeadMusic
     #   pos1 < pos2 # => true
     class MusicalPosition
       include Comparable
+      include RadixCarry
 
       # @return [Integer] the bar (measure) number (1-indexed)
       attr_reader :bar
@@ -170,19 +171,6 @@ module HeadMusic
 
       # Allow other MusicalPosition instances to access this method for comparison
       alias_method :to_i, :to_total_subticks
-
-      private
-
-      # Divide the named component by its radix, store the remainder back,
-      # and return the amount to carry into the next-higher component.
-      #
-      # @return [Integer] the carry (may be negative when borrowing)
-      def carry(component, radix)
-        ivar = :"@#{component}"
-        delta, remainder = instance_variable_get(ivar).divmod(radix)
-        instance_variable_set(ivar, remainder)
-        delta
-      end
     end
   end
 end

data/lib/head_music/time/radix_carry.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module HeadMusic
+  module Time
+    # Shared helper for positional/timecode components that carry between
+    # radix-bounded fields (e.g. bars:beats:ticks, hours:minutes:seconds:frames).
+    module RadixCarry
+      private
+
+      # Divide the named component by its radix, store the remainder back,
+      # and return the amount to carry into the next-higher component.
+      #
+      # @return [Integer] the carry (may be negative when borrowing)
+      def carry(component, radix)
+        ivar = :"@#{component}"
+        delta, remainder = instance_variable_get(ivar).divmod(radix)
+        instance_variable_set(ivar, remainder)
+        delta
+      end
+    end
+  end
+end

data/lib/head_music/time/smpte_timecode.rb

@@ -33,6 +33,7 @@ module HeadMusic
     #   tc1 < tc2 # => true
     class SmpteTimecode
       include Comparable
+      include RadixCarry
 
       # @return [Integer] the hour component
       attr_reader :hour
@@ -148,19 +149,6 @@ module HeadMusic
 
       # Allow other SmpteTimecode instances to access this method for comparison
       alias_method :to_i, :to_total_frames
-
-      private
-
-      # Divide the named component by its radix, store the remainder back,
-      # and return the amount to carry into the next-higher component.
-      #
-      # @return [Integer] the carry (may be negative when borrowing)
-      def carry(component, radix)
-        ivar = :"@#{component}"
-        delta, remainder = instance_variable_get(ivar).divmod(radix)
-        instance_variable_set(ivar, remainder)
-        delta
-      end
     end
   end
 end

data/lib/head_music/time.rb

@@ -22,6 +22,7 @@ module HeadMusic
   end
 end
 
+require_relative "time/radix_carry"
 require_relative "time/clock_position"
 require_relative "time/musical_position"
 require_relative "time/smpte_timecode"

data/lib/head_music/version.rb

@@ -1,3 +1,3 @@
 module HeadMusic
-  VERSION = "17.4.0"
+  VERSION = "17.5.0"
 end

data/lib/head_music.rb

@@ -145,6 +145,7 @@ require "head_music/content/placement"
 require "head_music/content/position"
 require "head_music/content/sound_resolver"
 require "head_music/content/staff"
+require "head_music/content/syllable"
 require "head_music/content/voice"
 require "head_music/content/voice/melodic_note_pair"
 require "head_music/content/voice/melodic_line"

data/user-stories/done/lyrics.md

@@ -0,0 +1,162 @@
+<!--
+metadata:
+  created_at:   2026-07-21T10:29:08-07:00
+  activated_at: 2026-07-21T10:36:39-07:00
+  planned_at:   2026-07-21T10:39:08-07:00
+  finished_at:  2026-07-21T16:42:58-07:00
+  updated_at:   2026-07-21T16:42:58-07:00
+-->
+
+# Story: Lyrics
+
+## Summary
+
+AS a composer working with vocal music in head_music
+I WANT to attach sung text (lyrics) to the notes of a voice
+SO THAT compositions can carry multi-verse, hyphenated lyrics and export them to MusicXML
+
+## Acceptance Criteria
+
+- A `Placement` can carry sung text: at most one syllable per verse, keyed by verse number, with rests and un-texted placements carrying none.
+- Multiple verses are supported (e.g. verse 1 "glo-", verse 2 "peace" on the same note).
+- A syllable stores only the minimal linguistic fact — its text, its verse, and a `hyphen_after` boolean indicating the word continues onto the next sung note. The MusicXML `syllabic` value (single/begin/middle/end) is NOT stored.
+- Melisma (one syllable held over several notes) is represented by absence: the held notes simply carry no syllable for that verse. No melisma flag is stored.
+- Syllables round-trip losslessly through `Placement#to_h` and the composition hash deserializer.
+- MusicXML export emits `<lyric number="N">` as the last child of `<note>`, on the lead note of a chord only and the attack of a tied chain only, deriving `<syllabic>` from the stored `hyphen_after` booleans of the syllable and its predecessor in the same verse.
+- Lyric text is XML-escaped on export.
+- Test coverage stays at or above the project's 90% minimum, with the MusicXML spec ladder covering: single-verse single word, hyphenated word (begin/middle/end derivation), melisma (gap emits no `<lyric>`), and multi-verse.
+
+## Notes
+
+Design decisions reached in discussion (2026-07-21):
+
+**Model: store the linguistic fact, derive the notation.** A note (`Placement`) is associated with at most one syllable per verse, and often none. `syllabic` (single/begin/middle/end) is derivable from a single `hyphen_after` boolean per syllable and is therefore NOT stored — storing it would be a denormalization that can go inconsistent, and it mixes a notation-rendering concern into the `Content` layer, which this codebase deliberately keeps separate from `Notation`. Melisma is likewise not stored; it is the absence of a syllable on a following placement (MusicXML's continuation-by-absence).
+
+Lossless MusicXML *import* is explicitly NOT a goal, which is what frees us to derive `syllabic` on write rather than store it.
+
+**`Syllable` value object** (`lib/head_music/content/syllable.rb`): immutable, `text` / `verse` / `hyphen_after`, with `to_h` / `from_h` / `==` / `hyphen_after?`.
+
+**`Placement` changes** (mirror the existing `beam_break_before` side-metadata pattern):
+
+- `syllables` — a hash keyed by verse number, at most one `Syllable` per verse (structural enforcement of the invariant).
+- `sing(text, verse: 1, hyphen_after: false)` — assign; returns self for chaining.
+- `syllable(verse = 1)`, `sung?`.
+- `to_h` serializes syllables in verse order (alongside the `beam_break_before` line).
+- `merge` keeps the existing placement's syllables and ignores the incoming one — a chord sings one syllable per verse; syllables attach to the note event, not to individual chord tones.
+
+**Hash round-trip**: `HashDeserializer` restores syllables beside the `beam_break_before` restore; add a `values.placement_syllables` helper that validates (text present, verse a positive integer, no duplicate verse) the same way sounds/rhythmic values are validated on import.
+
+**MusicXML output** (`music_xml/writer.rb`): `<lyric>` is the last child of `<note>`, after `<notations>`. Rides the lead note of a chord only and the attack (`!component.tie_stop`) only. Derive `syllabic` by comparing this syllable's `hyphen_after?` with the previous sung note's for the same verse:
+
+| from prev? | to next? | syllabic |
+|---|---|---|
+| no | no | single |
+| no | yes | begin |
+| yes | yes | middle |
+| yes | no | end |
+
+Prefer precomputing a per-verse ordered list of sung placements once (O(n)) over re-walking the voice for each note. Text goes through the existing `escape` helper.
+
+**Deferred (out of scope for this story):**
+
+- ABC `w:` lyric-line parsing — stays an `:unsupported` token in the body lexer. The `Syllable` model is designed to receive it later (space / `-` / `_` / `*` alignment grammar → `Syllable`s).
+- MusicXML `<extend/>` melisma extender line rendering.
+
+## Implementation Plan
+
+Derived from the design in Notes (verified against current code 2026-07-21). Six steps, built in dependency order with tests at each step so coverage never dips below 90%.
+
+### Step 1 — `Syllable` value object
+
+New file `lib/head_music/content/syllable.rb`. Immutable (`freeze` in initialize). Attributes `text`, `verse`, `hyphen_after`. Methods: `hyphen_after?`, `to_h` (omit `verse` when 1 and `hyphen_after` when false), `self.from_h`, `==` (by `to_h`). Require it from `lib/head_music.rb` alongside the other `content/` requires. Spec: `spec/head_music/content/syllable_spec.rb`.
+
+### Step 2 — `Placement` sung-text API
+
+Edit `lib/head_music/content/placement.rb` (mirror the `beam_break_before` side-metadata pattern):
+
+- `syllables` — lazily-initialized hash keyed by verse number (`@syllables ||= {}`).
+- `sing(text, verse: 1, hyphen_after: false)` — assigns a `Syllable`, returns `self`.
+- `syllable(verse = 1)` — reader; `sung?` — `syllables.any?`.
+- `to_h` — after the `beam_break_before` line, add `hash["syllables"] = syllables.keys.sort.map { |v| syllables[v].to_h }` unless empty.
+- `merge` — keep the receiver's `@syllables`, ignore the incoming placement's (chords sing one syllable per verse); add a one-line comment.
+
+Spec additions in `spec/head_music/content/placement_spec.rb`: assignment, multi-verse, `to_h` shape + ordering, rests carry none, merge keeps existing syllables.
+
+### Step 3 — Hash round-trip
+
+Edit `lib/head_music/content/composition/schema_values.rb`: add `placement_syllables(placement_hash, path)` — returns `[]` when key absent; else require an Array; validate each entry (Hash, non-empty `text` String, `verse` a positive Integer defaulting to 1, no duplicate verse) and build via `Syllable.from_h`, raising `ArgumentError` with path context like the sibling validators.
+
+Edit `lib/head_music/content/composition/hash_deserializer.rb`: beside the `beam_break_before` restore in `build_voices`, add — when `placement_hash.key?("syllables")` — a loop calling `placement.sing(...)` for each validated syllable.
+
+Specs: `schema_values_spec.rb` (valid + each rejection path) and a composition round-trip (`to_h` → `HashDeserializer#composition` preserves syllables).
+
+### Step 4 — MusicXML `<lyric>` output
+
+Edit `lib/head_music/notation/music_xml/writer.rb`:
+
+- In `note_element_lines`, insert `*lyric_lines(placement, component, chord: chord)` after `notation_lines`, before `</note>`.
+- `lyric_lines` — return `[]` when `chord`, `placement.rest?`, or `component.tie_stop`. Else, for each verse in `placement.syllables.keys.sort`, emit `<lyric number="N">` / `<syllabic>` / `<text>` (escaped) / `</lyric>`.
+- `syllabic(placement, syllable)` — derive from `previous_syllable(placement, syllable.verse)&.hyphen_after?` and `syllable.hyphen_after?` per the truth table in Notes.
+- `previous_syllable(placement, verse)` — memoized per `[voice, verse]`: `placement.voice.placements.select { |p| p.syllable(verse) }` (already position-sorted), return the entry before `placement` (nil if first/absent). Melisma gaps are skipped naturally since only sung placements are collected.
+
+Spec ladder in `spec/head_music/notation/music_xml/writer_spec.rb` (or a focused lyric spec): single-verse single word (`single`), hyphenated word (`begin`/`middle`/`end`), melisma (held note emits no `<lyric>`), multi-verse (two `<lyric number>` on one note), chord lead-note-only, tie attack-only, XML escaping.
+
+### Step 5 — Validation & coverage
+
+Run `bundle exec rubocop -a`, then `bundle exec rake` (tests + coverage). Confirm ≥90% and that every new file/branch is exercised.
+
+### Step 6 — Verify acceptance criteria
+
+Walk each criterion against the code and tests; note any that need manual confirmation.
+
+Out of scope (deferred, per Notes): ABC `w:` parsing and the MusicXML `<extend/>` melisma line.
+
+## Review
+
+Reviewed 2026-07-21 against commit `8a91b69` (plus a follow-up fix applied during review, see below). Full suite: 6097 examples, 0 failures; coverage 99.69% line / 97.74% branch. Reviewed by a product-manager agent (acceptance criteria) and a code-reviewer agent (quality), on a clean story branch.
+
+### Acceptance criteria
+
+| # | Criterion | Verdict | Evidence |
+|---|---|---|---|
+| 1 | ≤1 syllable per verse, keyed by verse; rests/un-texted carry none | ✅ met | `placement.rb` `syllables` verse-keyed hash structurally enforces it; default empty (`placement_spec.rb` "carries no syllables by default") |
+| 2 | Multiple verses | ✅ met | `sing(..., verse:)`; `placement_spec.rb` multi-verse + `writer_spec.rb` one `<lyric>` per verse |
+| 3 | Stores only text/verse/hyphen_after; `syllabic` not stored | ✅ met | `syllable.rb` exposes exactly those three; no `syllabic` field anywhere |
+| 4 | Melisma by absence, no flag | ✅ met | no melisma field; `writer_spec.rb` two-note melisma emits one `<lyric>` |
+| 5 | Round-trips through `to_h` + deserializer | ✅ met | `to_h` verse-ordered; `SchemaValues#placement_syllables` validates; `composition_serialization_spec.rb` end-to-end round trip |
+| 6 | `<lyric number>` last child, lead/attack only, derived `syllabic` | ✅ met | `lyric_lines` last in `note_element_lines`, guards `chord \|\| rest? \|\| tie_stop`; derivation table covered by chord/tie/begin-middle-end specs |
+| 7 | Text XML-escaped | ✅ met | `escape(...)` in `lyric_lines`; `writer_spec.rb` `"R&D <x>"` parses back intact |
+| 8 | Coverage ≥90% + MusicXML spec ladder | ✅ met | 99.69% line; ladder (single/hyphenated/melisma/multi-verse) all present |
+
+All eight met. Nothing blocks `finish`.
+
+### Code review findings
+
+1. **(Important — found and fixed during review) `sing` keyed `syllables` by the raw `verse` argument while `Syllable` coerces it via `Integer()`.** `sing("la", verse: "2")` stored under key `"2"` while `syllable(2)` looked up the integer and returned `nil`; mixing key types made `syllables.keys.sort` raise in both `to_h` and the writer. No internal caller triggered it (all pass integers), but it was a latent bug in the public API. **Fixed:** `sing` now keys by `syllable.verse` (the coerced value). Added regression tests in `placement_spec.rb` (string verse found by its integer; mixed-type verses sort without raising).
+
+2. **(Minor — addressed) `previous_syllable` relied on an unstated invariant.** `Array#index` compares with `==`, which on `Placement` is position-only; it locates the right placement only because a voice holds one placement per position. Added a "why" comment documenting the dependency.
+
+3. **(Minor — addressed) behavioral-assertion gaps.** Added `writer_spec.rb` tests for a hyphenated word straddling a melisma gap (begin/middle/end skipping an un-sung note) and for per-verse independent `syllabic` derivation.
+
+4. **(Noted, not actioned) `hyphen_after` isn't validated on import** — any truthy JSON value becomes `true` via `Syllable`'s `!!`. Theoretical only (real JSON always sends a boolean); left as-is.
+
+5. **(Noted, not actioned) layer asymmetry** — `Placement#sing` accepts any positive/`Integer()`-coercible verse, while import rejects `verse <= 0`. The public contract expects `verse >= 1`; no criterion requires validation at `sing`. Left as a known minor asymmetry.
+
+## Learnings
+
+**What went well**
+
+- Front-loading the design debate paid off. Settling "store the linguistic fact, derive the notation" before any code — grounded in the Content/Notation boundary this codebase already maintains — made the implementation plan nearly write itself and kept the model minimal.
+- Mirroring the existing `beam_break_before` side-metadata pattern gave a proven path through placement metadata → `to_h` → validated deserialization, so each layer was low-risk and consistent with existing code.
+- Deriving `syllabic` on write made melisma free: "no syllable on the held note" is the whole implementation, no stored flag needed.
+
+**What was surprising**
+
+- Adversarial review earned its keep. The verse-key coercion bug (`sing(verse: "2")` stored under `"2"`, `syllable(2)` returned `nil`, mixed keys crashed `keys.sort`) was invisible to every happy-path test because all internal callers pass integers. Only skeptical review surfaced it.
+- The tooling had its own bug — the board generator's `\s*` swallowed newlines and zeroed every sort timestamp. The scaffolding around the work needed the same scrutiny as the work.
+- A public API (`sing`) accepted input the import layer rejected — a layer asymmetry that normal use never hits.
+
+**What to do differently**
+
+- When adding per-note metadata, write the round-trip and a coercion/edge test up front — coercion mismatches don't show up in happy-path specs.
+- Decide deliberately whether validation belongs at the write boundary (`sing`) as well as the import boundary, so the layers agree rather than drift.

data/user-stories/index.html

@@ -277,6 +277,10 @@
   ],
   "active": [],
   "done": [
+    {
+      "title": "Lyrics",
+      "path": "done/lyrics.md"
+    },
     {
       "title": "ABC Notation Beaming",
       "path": "done/abc-notation-beaming.md"
@@ -399,15 +403,15 @@
     },
     {
       "title": "Untitled",
-      "path": "done/expand-playing-techniques.md"
+      "path": "done/superclass-for-note.md"
     },
     {
       "title": "Untitled",
-      "path": "done/instrument-variant.md"
+      "path": "done/expand-playing-techniques.md"
     },
     {
       "title": "Untitled",
-      "path": "done/superclass-for-note.md"
+      "path": "done/instrument-variant.md"
     }
   ]
 };

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: head_music
 version: !ruby/object:Gem::Version
-  version: 17.4.0
+  version: 17.5.0
 platform: ruby
 authors:
 - Rob Head
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-20 00:00:00.000000000 Z
+date: 2026-07-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -34,16 +34,22 @@ dependencies:
   name: humanize
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
 - !ruby/object:Gem::Dependency
   name: i18n
   requirement: !ruby/object:Gem::Requirement
@@ -210,6 +216,7 @@ files:
 - lib/head_music/content/position.rb
 - lib/head_music/content/sound_resolver.rb
 - lib/head_music/content/staff.rb
+- lib/head_music/content/syllable.rb
 - lib/head_music/content/voice.rb
 - lib/head_music/content/voice/melodic_line.rb
 - lib/head_music/content/voice/melodic_note_pair.rb
@@ -433,6 +440,7 @@ files:
 - lib/head_music/time/meter_map.rb
 - lib/head_music/time/musical_position.rb
 - lib/head_music/time/musical_time_converter.rb
+- lib/head_music/time/radix_carry.rb
 - lib/head_music/time/smpte_converter.rb
 - lib/head_music/time/smpte_timecode.rb
 - lib/head_music/time/tempo_event.rb
@@ -470,6 +478,7 @@ files:
 - user-stories/done/handle-time.rb
 - user-stories/done/instrument-architecture.md
 - user-stories/done/instrument-variant.md
+- user-stories/done/lyrics.md
 - user-stories/done/melody-contour-guides.md
 - user-stories/done/move-musical-symbol-to-notation.md
 - user-stories/done/move-staff-mapping-to-notation.md