head_music 17.4.0 → 18.0.0

data/lib/head_music/notation/abc/key_mapper.rb

@@ -4,7 +4,10 @@
 # KeySignature.get, which splits tonic and scale type on whitespace,
 # so the mode word is normalized into a "tonic mode" string first.
 class HeadMusic::Notation::ABC::KeyMapper
-  KEY_PATTERN = /\A([A-G])([#♯b♭]?)\s*([A-Za-z]*)/
+  # The alteration group wraps the pattern in (?:...) before making it optional.
+  # Writing (...)? instead leaves match[2] nil for every unaltered key ("C", "Ador"),
+  # which raises downstream where the capture is interpolated into a string.
+  KEY_PATTERN = /\A([A-G])((?:#{HeadMusic::Rudiment::Alteration::PATTERN.source})?)\s*([A-Za-z]*)/
 
   # Mode words are matched case-insensitively on their first three letters,
   # so abbreviations ("dor") and full names ("Dorian") both resolve.
@@ -48,9 +51,15 @@ class HeadMusic::Notation::ABC::KeyMapper
       raise_render_error("Cannot render double-altered tonic #{spelling} in an ABC K: field")
     end
 
-    # ABC convention uses ASCII "#"/"b" rather than the unicode signs
-    # that Spelling#to_s produces.
-    "#{spelling.letter_name}#{alteration&.ascii}"
+    # ABC convention uses ASCII "#"/"b" rather than the unicode signs that
+    # Spelling#to_s produces. The double-altered guard above runs first, since this
+    # would otherwise happily emit "Cx".
+    #
+    # A natural sign is dropped rather than converted. Accidentals.to_ascii preserves
+    # "♮" on purpose — mapping it away would turn the spelling "C♮" into the different
+    # spelling "C" — but an ABC K: field has no way to express a natural tonic, and
+    # "C♮ major" names the same key signature as "C major".
+    HeadMusic::Utilities::Accidentals.to_ascii(spelling.to_s).delete("♮")
   end
   private_class_method :tonic_string
 
@@ -87,7 +96,18 @@ class HeadMusic::Notation::ABC::KeyMapper
       raise_parse_error("Unrecognized key")
   end
 
+  # An ABC K: field cannot express a double-altered tonic, and .abc_value raises
+  # rather than rendering one. Reject it on the way in too: KEY_PATTERN interpolates
+  # the whole Alteration::PATTERN so that "bb" and "##" bind correctly, which also
+  # makes them matchable here. Without this guard "K:Cx" would parse to C𝄪 major and
+  # report "no sharps or flats" — a plausible-looking wrong answer where the narrower
+  # pattern used to give a clear parse error.
   def tonic
+    alteration = HeadMusic::Rudiment::Alteration.get(match[2])
+    if alteration && (alteration.double_sharp? || alteration.double_flat?)
+      raise_parse_error("Cannot express double-altered tonic #{match[1]}#{match[2]} in an ABC K: field")
+    end
+
     match[1] + match[2]
   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/rudiment/alteration.rb

@@ -15,7 +15,15 @@ class HeadMusic::Rudiment::Alteration < HeadMusic::Rudiment::Base
     YAML.load_file(File.expand_path("alterations.yml", __dir__), symbolize_names: true)[:alterations].freeze
 
   ALTERATION_IDENTIFIERS = ALTERATION_RECORDS.keys.freeze
-  SYMBOLS = ALTERATION_RECORDS.map { |key, attributes| attributes[:symbols].map { |symbol| [symbol[:unicode], symbol[:ascii]] } }.flatten.reject { |s| s.nil? || s.empty? }.freeze
+  # Sorted longest-first because Regexp.union alternates in array order rather than by
+  # longest match. Without it, "bb" would match the single-flat branch and leave a
+  # stray "b" behind, half-converting a double. Ordering among equal-length symbols is
+  # unspecified and does not matter: equal-length strings cannot prefix one another.
+  SYMBOLS = ALTERATION_RECORDS
+    .map { |key, attributes| attributes[:symbols].map { |symbol| [symbol[:unicode], symbol[:ascii]] } }
+    .flatten.reject { |s| s.nil? || s.empty? }.uniq
+    .sort_by { |symbol| -symbol.length }
+    .freeze
   PATTERN = Regexp.union(SYMBOLS)
   MATCHER = PATTERN
 
@@ -24,7 +32,7 @@ class HeadMusic::Rudiment::Alteration < HeadMusic::Rudiment::Base
   end
 
   def self.symbols
-    @symbols ||= all.map { |alteration| [alteration.ascii, alteration.unicode] }.flatten.reject { |s| s.nil? || s.empty? }
+    SYMBOLS
   end
 
   def self.symbol?(candidate)
@@ -53,9 +61,16 @@ class HeadMusic::Rudiment::Alteration < HeadMusic::Rudiment::Base
     super || identifier.to_s.tr("_", " ")
   end
 
-  def representations
-    [identifier, identifier.to_s, name, ascii, unicode, html_entity]
-      .reject { |representation| representation.to_s.strip == "" }
+  # Spans every symbol record, not just the primary one, so that an alternate ASCII
+  # spelling like "##" resolves through .get. Memoized per locale because .get runs on
+  # every parse and walks this list for each alteration, and #name is locale-dependent.
+  def representations(locale_code: I18n.locale)
+    @representations ||= {}
+    @representations[locale_code] ||=
+      ([identifier, identifier.to_s, name(locale_code: locale_code)] +
+        musical_symbols.flat_map { |symbol| [symbol.ascii, symbol.unicode, symbol.html_entity] })
+        .uniq
+        .reject { |representation| representation.to_s.strip == "" }
   end
 
   ALTERATION_RECORDS.keys.each do |key|

data/lib/head_music/rudiment/alterations.yml

@@ -27,6 +27,12 @@ alterations:
   double_sharp:
     semitones: 2
     symbols:
+      # "x" stays first: #ascii reads the first record, and ABC's accidental table
+      # is keyed on "x". "##" is accepted as input for symmetry with "bb", but is
+      # never emitted.
       - ascii: "x"
         unicode: "𝄪"
         html_entity: "𝄪"
+      - ascii: "##"
+        unicode: "𝄪"
+        html_entity: "𝄪"

data/lib/head_music/rudiment/key_signature.rb

@@ -18,7 +18,7 @@ class HeadMusic::Rudiment::KeySignature < HeadMusic::Rudiment::Base
 
     if identifier.is_a?(String)
       tonic_spelling, scale_type_name = identifier.strip.split(/\s/)
-      hash_key = HeadMusic::Utilities::HashKey.for(identifier.gsub(/#|♯/, " sharp").gsub(/(\w)[b♭]/, '\\1 flat'))
+      hash_key = HeadMusic::Utilities::HashKey.for(identifier)
       @key_signatures[hash_key] ||= new(tonic_spelling, scale_type_name)
     elsif identifier.is_a?(HeadMusic::Rudiment::DiatonicContext)
       identifier.key_signature

data/lib/head_music/rudiment/note.rb

@@ -16,8 +16,12 @@ class HeadMusic::Rudiment::Note < HeadMusic::Rudiment::RhythmicElement
   delegate :pitch_class, :midi_note_number, :frequency, to: :pitch
 
   # Regex pattern for parsing note strings like "C#4 quarter" or "Eb3 dotted half"
-  # Extract the core pattern from Spelling::MATCHER without anchors
-  PITCH_PATTERN = /([A-G])(#{HeadMusic::Rudiment::Alteration::PATTERN.source}?)(-?\d+)?/i
+  # Extract the core pattern from Spelling::MATCHER without anchors.
+  #
+  # The alteration group wraps the whole pattern in (?:...) before making it
+  # optional. Interpolating "#{...}?" instead binds the "?" to the pattern's final
+  # alternative alone, which truncates "C##4" to a bare "C#" and loses the register.
+  PITCH_PATTERN = /([A-G])((?:#{HeadMusic::Rudiment::Alteration::PATTERN.source})?)(-?\d+)?/i
   MATCHER = /^\s*(#{PITCH_PATTERN.source})\s+(.+)$/i
 
   def self.get(pitch, rhythmic_value = nil)

data/lib/head_music/rudiment/scale.rb

@@ -3,15 +3,13 @@ module HeadMusic::Rudiment; end
 
 # A scale contains ordered pitches starting at a tonal center.
 class HeadMusic::Rudiment::Scale < HeadMusic::Rudiment::Base
-  SCALE_REGEX = /^[A-G][#b]?\s+\w+$/
-
   def self.get(root_pitch, scale_type = nil)
     root_pitch = HeadMusic::Rudiment::Pitch.get(root_pitch)
     scale_type = HeadMusic::Rudiment::ScaleType.get(scale_type || HeadMusic::Rudiment::ScaleType::DEFAULT)
     @scales ||= {}
-    hash_key = HeadMusic::Utilities::HashKey.for(
-      [root_pitch, scale_type].join(" ").gsub(/#|♯/, "sharp").gsub(/(\w)[b♭]/, '\\1flat')
-    )
+    # Pitch#to_s already emits unicode accidentals and HashKey already desymbolizes
+    # them, so no accidental normalization is needed here.
+    hash_key = HeadMusic::Utilities::HashKey.for([root_pitch, scale_type].join(" "))
     @scales[hash_key] ||= new(root_pitch, scale_type)
   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/utilities/accidentals.rb

@@ -0,0 +1,137 @@
+# A namespace for utilities classes and modules
+module HeadMusic::Utilities; end
+
+# Util for converting accidentals in a string between ASCII spellings and canonical
+# unicode glyphs.
+#
+# Safe to run over prose. Conversion happens only inside a candidate chord token — an
+# uppercase letter name that does not continue a longer word or number — so "Above",
+# "Bebop", "1.0b2", and "0x1B2F" are untouched while "Bb", "Ab7", "Bbm", and
+# "Bbmaj7#11" convert.
+#
+# Deliberately narrower than the gem's parsers in two ways, both of which follow from
+# being safe over prose:
+#
+# 1. Case-sensitive. Spelling and Pitch accept a lowercase letter name; this does not,
+#    because a case-insensitive rule reads the "B" of "B7" as a flat sign and every
+#    lowercase word in a sentence becomes a candidate. So to_unicode("eb") is "eb"
+#    while Spelling.get("eb") is "E♭".
+# 2. A bare accidental token is read as an accidental, not as a pitch name. to_unicode
+#    ("bb") is "𝄫" — the double-flat sign — while Spelling.get("bb") is "B♭". Callers
+#    holding a pitch name that may be lowercase should parse it with Spelling first.
+#
+# The maps are derived from Alteration lazily rather than at load time. Eager
+# derivation is not an option anywhere in the load sequence: Alteration.all
+# instantiates Notation::MusicalSymbol, which is not required until much later in
+# head_music.rb.
+class HeadMusic::Utilities::Accidentals
+  # Chord qualities that may follow a flat without a word boundary, so that "Bbm" and
+  # "Ebmaj7" convert while "Above" does not. "m" subsumes "maj", "min", and "m7";
+  # uppercase forms like "BbM7" already clear the (?![a-z]) guard unaided.
+  #
+  # Measured against /usr/share/dict/words: this list costs exactly two false
+  # positives ("Abmho", "Ebbman") across 235,976 capitalized words. Each entry clears
+  # a real word by one letter — "sus" vs "Absurd", "dim" vs "Abdomen" and "Abdicate" —
+  # so any addition here needs re-measuring rather than eyeballing.
+  CHORD_QUALITIES = %w[m dim aug sus].freeze
+
+  # The scale degrees a chord extension can alter. Requiring the altered degree to be
+  # one of these is what separates "C7b9" from "Figure C2b3": both are an accidental
+  # flanked by digits inside a token that opens with a letter name, and only the
+  # degree tells them apart.
+  EXTENSION_DEGREES = %w[13 11 9 6 5 4].freeze
+
+  # A candidate chord symbol. One quantifier over a character class, so there is no
+  # nesting and no ReDoS surface. This is what scopes the altered-extension rule
+  # below: "1.0b2" and "0x1B2F" never open a token, so they can never reach it.
+  CHORD_TOKEN = /(?<![A-Za-z0-9])[A-G][A-Za-z0-9#]*/
+
+  # "Bb" => "B♭", "C##" => "C𝄪", "Cx" => "C𝄪", "Bbmaj7#11" => "B♭maj7♯11".
+  # Idempotent, and all-or-nothing per accidental: a double never half-converts.
+  def self.to_unicode(text)
+    string = text.to_s
+    return unicode_for.fetch(string) if unicode_for.key?(string)
+
+    string.gsub(CHORD_TOKEN) do |token|
+      token.gsub(ascii_matcher) { |match| unicode_for.fetch(match) }
+    end
+  end
+
+  # "B♭" => "Bb", "C𝄪" => "Cx". Emits the spellings the gem's own parsers accept,
+  # so "x" rather than "##" for a double sharp.
+  #
+  # Deliberately not letter-anchored: unicode glyphs are unambiguous, and consumers
+  # feed this scale degrees and roman numerals ("♭7", "♭VI") that have no letter name.
+  # A natural sign is left as "♮" — mapping it to "" would turn the valid spelling
+  # "C♮" into the different spelling "C". Idempotent.
+  def self.to_ascii(text)
+    text.to_s.gsub(unicode_matcher) { |match| ascii_for.fetch(match) }
+  end
+
+  def self.unicode_for
+    @unicode_for ||=
+      altering_alterations.flat_map(&:musical_symbols)
+        .reject { |symbol| symbol.ascii.to_s.empty? }
+        .to_h { |symbol| [symbol.ascii, symbol.unicode] }
+  end
+
+  # One entry per alteration, keyed on its primary #ascii, so "##" is never emitted.
+  def self.ascii_for
+    @ascii_for ||= altering_alterations.to_h { |alteration| [alteration.unicode, alteration.ascii] }
+  end
+
+  # Applied only inside a CHORD_TOKEN. No /i flag — case-insensitivity would read the
+  # "B" of "B7" as a flat sign.
+  #
+  # Two anchor contexts. The first is the pitch name's own accidental, anchored to the
+  # letter name, with a per-family guard: "#" cannot occur in an English word at all,
+  # "b" can but is rescued by CHORD_QUALITIES, and "x" takes the bare guard because an
+  # allowlist there would buy "Cxm7" and cost "Axminster" and "Exmoor". The second is
+  # an altered extension ("7#11", "7b9"), which has no letter to anchor to and is
+  # instead flanked by digits. Being inside a CHORD_TOKEN is not sufficient on its own
+  # — "Figure C2b3" would qualify — so the altered degree must also be a real chord
+  # extension.
+  def self.ascii_matcher
+    @ascii_matcher ||=
+      /(?<=[A-G])(?:#{sharp_branch}|#{flat_branch}|#{double_sharp_branch})|#{extension_branch}/
+  end
+
+  def self.unicode_matcher
+    @unicode_matcher ||= Regexp.union(ascii_for.keys)
+  end
+  private_class_method :ascii_matcher, :unicode_matcher
+
+  def self.sharp_branch
+    longest_first(spellings_matching(/#/))
+  end
+
+  def self.flat_branch
+    "(?:#{longest_first(spellings_matching(/b/))})(?:(?![a-z])|(?=#{longest_first(CHORD_QUALITIES)}))"
+  end
+
+  def self.double_sharp_branch
+    "(?:#{longest_first(spellings_matching(/x/))})(?![a-z])"
+  end
+
+  def self.extension_branch
+    "(?<=\\d)(?:#{longest_first(spellings_matching(/[#b]/))})(?=(?:#{longest_first(EXTENSION_DEGREES)})(?![0-9]))"
+  end
+
+  def self.spellings_matching(pattern)
+    unicode_for.keys.grep(pattern)
+  end
+
+  # Regexp.union alternates in array order rather than by longest match, so every
+  # two-character spelling must precede its one-character prefix or a double
+  # half-converts.
+  def self.longest_first(spellings)
+    Regexp.union(spellings.sort_by { |spelling| -spelling.length }).source
+  end
+
+  def self.altering_alterations
+    HeadMusic::Rudiment::Alteration.all.reject(&:natural?)
+  end
+
+  private_class_method :sharp_branch, :flat_branch, :double_sharp_branch,
+    :extension_branch, :spellings_matching, :longest_first, :altering_alterations
+end

data/lib/head_music/utilities/hash_key.rb

@@ -3,39 +3,54 @@ module HeadMusic::Utilities; end
 
 # Util for converting an object to a consistent hash key
 class HeadMusic::Utilities::HashKey
+  # Keyed on the identifier as given, so a symbol and its string spelling occupy
+  # separate entries for the same result. Never evicted: the gem's identifiers come
+  # from finite catalogs, so the vocabulary is bounded. A caller generating
+  # identifiers dynamically would grow this without limit.
   def self.for(identifier)
     @hash_keys ||= {}
-    @hash_keys[identifier] ||= new(identifier).to_sym
+    @hash_keys[identifier] ||=
+      HeadMusic::Utilities::Case.to_snake_case(
+        I18n.transliterate(desymbolized_string(identifier))
+      ).to_sym
   end
 
-  attr_reader :original
-
-  def initialize(identifier)
-    @original = identifier
-  end
-
-  def to_sym
-    normalized_string.to_sym
-  end
-
-  private
-
-  def normalized_string
-    @normalized_string ||=
-      HeadMusic::Utilities::Case.to_snake_case(transliterated_string)
-  end
-
-  def transliterated_string
-    I18n.transliterate(desymbolized_string)
-  end
-
-  def desymbolized_string
-    original.to_s
-      .gsub("𝄫", "_double_flat")
-      .gsub("♭", "_flat")
-      .gsub("♮", "_natural")
-      .gsub("♯", "_sharp")
+  # Accidentals become word suffixes, so that "C♯" and "C sharp" reach the same key.
+  #
+  # ASCII spellings are normalized to their unicode glyphs first rather than mapped
+  # here. Mapping ASCII "b" directly is what a naive implementation gets wrong — it
+  # turns :bass_clarinet into :b_flatass_clarinet — and avoiding that by handling
+  # ASCII "#" but not ASCII "b" left the two sides asymmetric, with "C#" keying to
+  # :c_sharp while "Bb" keyed to :bb. Accidentals.to_unicode is prose-safe, so it
+  # closes that gap without the mangling.
+  #
+  # The two ASCII sharp rules that follow are a fallback, not a second inventory. They
+  # catch a "#" that Accidentals.to_unicode leaves alone because it is not attached to
+  # a letter name, and they are safe to apply bare because "#" cannot occur in a word —
+  # which is exactly why the corresponding ASCII flat rules must not exist here.
+  # Doubles first: the single rule would otherwise consume the first "#" of a "##".
+  def self.desymbolized_string(identifier)
+    normalized = HeadMusic::Utilities::Accidentals.to_unicode(identifier)
+    word_suffixes
+      .reduce(normalized) { |string, (glyph, suffix)| string.gsub(glyph, suffix) }
+      .gsub("##", "_double_sharp")
       .gsub("#", "_sharp")
-      .gsub("𝄪", "_double_sharp")
   end
+  private_class_method :desymbolized_string
+
+  # Derived from Alteration so that alterations.yml stays the only place the glyph
+  # inventory lives. Each alteration's identifier is already the word form a key wants
+  # (:double_sharp -> "_double_sharp"). Every unicode glyph is a single character, so
+  # unlike the ASCII spellings they need no longest-first ordering.
+  #
+  # Resolved lazily, and it must stay that way: Alteration includes Named, whose
+  # .get_by_name calls back into HashKey. Nothing on Alteration's initialization path
+  # reaches that method today, which is what keeps the cycle from closing — so if
+  # Named ever starts building a hash key while constructing an object, this memo
+  # would recurse through a half-built Alteration.all.
+  def self.word_suffixes
+    @word_suffixes ||=
+      HeadMusic::Rudiment::Alteration.all.to_h { |alteration| [alteration.unicode, "_#{alteration.identifier}"] }
+  end
+  private_class_method :word_suffixes
 end

data/lib/head_music/version.rb

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

data/lib/head_music.rb

@@ -18,11 +18,11 @@ require "i18n/backend/fallbacks"
 
 # Configure I18n for HeadMusic locales
 # Include fallbacks backend if not already included.
-# :nocov: — one-time, load-order-dependent bootstrap guard; module inclusion is
-# irreversible, so the fresh-install arm cannot be re-exercised in-process. The
-# already-included arm is asserted by the idempotency spec.
+# simplecov:disable — one-time, load-order-dependent bootstrap guard; module
+# inclusion is irreversible, so the fresh-install arm cannot be re-exercised
+# in-process. The already-included arm is asserted by the idempotency spec.
 I18n::Backend::Simple.include(I18n::Backend::Fallbacks) unless I18n::Backend::Simple.included_modules.include?(I18n::Backend::Fallbacks)
-# :nocov:
+# simplecov:enable
 
 # Add HeadMusic locale files to the load path (additive, doesn't overwrite)
 I18n.load_path += Dir[File.join(File.dirname(__dir__), "lib", "head_music", "locales", "*.yml")]
@@ -45,14 +45,15 @@ HEAD_MUSIC_FALLBACKS = {
 }.freeze
 
 HEAD_MUSIC_FALLBACKS.each do |locale, fallbacks|
-  # :nocov: — load-order-dependent bootstrap guard; whether the fresh-configure
-  # arm runs depends on global I18n state at first require. The already-configured
-  # arm is asserted by the idempotency spec.
+  # simplecov:disable — load-order-dependent bootstrap guard; whether the
+  # fresh-configure arm runs depends on global I18n state at first require. The
+  # already-configured arm is asserted by the idempotency spec.
   I18n.fallbacks[locale] = fallbacks if I18n.fallbacks[locale].empty? || I18n.fallbacks[locale] == [locale]
-  # :nocov:
+  # simplecov:enable
 end
 
 # utilities
+require "head_music/utilities/accidentals"
 require "head_music/utilities/case"
 require "head_music/utilities/hash_key"
 
@@ -145,6 +146,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"