musa-dsl 0.30.2 → 0.40.0

data/lib/musa-dsl/datasets/gdvd.rb

@@ -5,6 +5,117 @@ require_relative 'helper'
 
 
 module Musa::Datasets
+  # Delta-encoded score events for efficient compression.
+  #
+  # GDVd (Grade/Duration/Velocity delta) represents musical events using
+  # delta encoding - storing only changes from previous events.
+  # Extends {DeltaD} for flexible duration encoding and {DeltaI} for indexed deltas.
+  #
+  # ## Purpose
+  #
+  # GDVd provides efficient delta encoding for musical sequences:
+  #
+  # - **Compact storage**: Only changed values are stored
+  # - **Efficient serialization**: Neuma format uses delta notation
+  # - **Lossless compression**: Full reconstruction via {#to_gdv}
+  # - **Musical patterns**: Captures relative motion (intervals, velocity changes)
+  #
+  # ## Encoding Types
+  #
+  # Each parameter can be encoded as absolute or delta:
+  #
+  # ### Pitch Encoding
+  #
+  # **Absolute**:
+  #
+  # - **abs_grade**: Set grade to specific value
+  # - **abs_sharps**: Set chromatic alteration
+  # - **abs_octave**: Set octave to specific value
+  #
+  # **Delta**:
+  #
+  # - **delta_grade**: Change grade by semitones
+  # - **delta_sharps**: Change chromatic alteration
+  # - **delta_interval**: Change by scale interval (with delta_interval_sign)
+  # - **delta_octave**: Change octave
+  #
+  # ### Duration Encoding (from {DeltaD})
+  #
+  # - **abs_duration**: Set duration
+  # - **delta_duration**: Add to duration
+  # - **factor_duration**: Multiply duration
+  #
+  # ### Velocity Encoding
+  #
+  # - **abs_velocity**: Set velocity
+  # - **delta_velocity**: Add to velocity
+  #
+  # ## Natural Keys
+  #
+  # - **:abs_grade**, **:abs_sharps**, **:abs_octave**: Absolute pitch
+  # - **:delta_grade**, **:delta_sharps**, **:delta_interval**, **:delta_interval_sign**, **:delta_octave**: Delta pitch
+  # - **:abs_velocity**, **:delta_velocity**: Velocity encoding
+  # - **:abs_duration**, **:delta_duration**, **:factor_duration**: Duration encoding
+  # - **:modifiers**: Hash of additional modifiers
+  #
+  # ## Reconstruction
+  #
+  # Delta events require a previous event for reconstruction:
+  #
+  #     gdvd = { delta_grade: 2, delta_velocity: 1 }.extend(GDVd)
+  #     previous = { grade: 0, octave: 0, duration: 1.0, velocity: 0 }.extend(GDV)
+  #     gdv = gdvd.to_gdv(scale, previous: previous)
+  #     # => { grade: 2, octave: 0, duration: 1.0, velocity: 1 }
+  #
+  # ## Neuma Delta Notation
+  #
+  # Delta events use special notation in Neuma format:
+  #
+  # - **Delta grade**: "+2" or "-2" (semitone change)
+  # - **Delta sharps**: "+#" or "-_" (chromatic change)
+  # - **Delta octave**: "+o1" or "-o1" (octave change)
+  # - **Delta duration**: "+0.5" or "-0.5" (duration change)
+  # - **Factor duration**: "*2" or "*0.5" (duration multiply)
+  # - **Delta velocity**: "+f" or "-f" (dynamics change)
+  #
+  # @example First event (absolute encoding)
+  #   gdvd = { abs_grade: 0, abs_duration: 1.0, abs_velocity: 0 }.extend(GDVd)
+  #   gdvd.base_duration = 1/4r
+  #   gdvd.to_neuma  # => "(0 4 mp)"
+  #
+  # @example Delta encoding (unchanged duration)
+  #   gdvd = { delta_grade: 2, delta_velocity: 1 }.extend(GDVd)
+  #   gdvd.base_duration = 1/4r
+  #   gdvd.to_neuma  # => "(+2 +f)"
+  #   # Grade +2 semitones, velocity +1 (one f louder)
+  #
+  # @example Chromatic change
+  #   gdvd = { delta_sharps: 1 }.extend(GDVd)
+  #   gdvd.to_neuma  # => "(+#)"
+  #   # Add one sharp
+  #
+  # @example Duration multiplication
+  #   gdvd = { factor_duration: 2 }.extend(GDVd)
+  #   gdvd.base_duration = 1/4r
+  #   gdvd.to_neuma  # => "(. *2)"
+  #   # Double duration
+  #
+  # @example Reconstruction from delta
+  #   previous = { grade: 0, octave: 0, duration: 1.0, velocity: 0 }.extend(GDV)
+  #   gdvd = { delta_grade: 2, delta_velocity: 1 }.extend(GDVd)
+  #   scale = Musa::Scales::Scales.et12[440.0].major[60]
+  #   gdv = gdvd.to_gdv(scale, previous: previous)
+  #   # => { grade: 2, octave: 0, duration: 1.0, velocity: 1 }
+  #
+  # @example Octave change
+  #   gdvd = { delta_grade: -2, delta_octave: 1 }.extend(GDVd)
+  #   gdvd.to_neuma  # => "(-2 +o1)"
+  #   # Down 2 semitones, up one octave
+  #
+  # @see GDV Absolute score notation
+  # @see DeltaD Delta duration encoding
+  # @see DeltaI Delta indexed encoding
+  # @see Helper String formatting utilities
   module GDVd
     include DeltaD
     include DeltaI
@@ -13,14 +124,28 @@ module Musa::Datasets
 
     using Musa::Extension::InspectNice
 
+    # Natural keys for delta encoding.
+    # @return [Array<Symbol>]
     NaturalKeys = (NaturalKeys +
                     [:abs_grade, :abs_sharps, :abs_octave,
                      :delta_grade, :delta_sharps, :delta_interval_sign, :delta_interval, :delta_octave,
                      :abs_velocity, :delta_velocity,
                      :modifiers]).freeze
 
+    # Base duration for time calculations.
+    # @return [Rational]
     attr_reader :base_duration
 
+    # Sets base duration, adjusting existing duration values.
+    #
+    # When base_duration changes, existing abs_duration and delta_duration
+    # are scaled proportionally to maintain actual time values.
+    #
+    # @param value [Rational] new base duration
+    #
+    # @example
+    #   gdvd[:abs_duration] = 1.0
+    #   gdvd.base_duration = 1/4r  # abs_duration scaled by factor
     def base_duration=(value)
       factor = value / (@base_duration || 1)
       @base_duration = value
@@ -29,6 +154,33 @@ module Musa::Datasets
       self[:delta_duration] *= factor if has_key?(:delta_duration)
     end
 
+    # Reconstructs absolute GDV from delta encoding.
+    #
+    # Applies delta changes to previous event to create new absolute event.
+    # Handles all encoding types (abs_, delta_, factor_) appropriately.
+    #
+    # @param scale [Musa::Scales::Scale] reference scale for pitch calculations
+    # @param previous [GDV] previous absolute event (required for reconstruction)
+    #
+    # @return [GDV] reconstructed absolute event
+    #
+    # @example Basic delta reconstruction
+    #   previous = { grade: 0, octave: 0, duration: 1.0, velocity: 0 }.extend(GDV)
+    #   gdvd = { delta_grade: 2, delta_velocity: 1 }.extend(GDVd)
+    #   gdv = gdvd.to_gdv(scale, previous: previous)
+    #   # => { grade: 2, octave: 0, duration: 1.0, velocity: 1 }
+    #
+    # @example Absolute override
+    #   previous = { grade: 0, duration: 1.0 }.extend(GDV)
+    #   gdvd = { abs_grade: 5, abs_duration: 2.0 }.extend(GDVd)
+    #   gdv = gdvd.to_gdv(scale, previous: previous)
+    #   # => { grade: 5, duration: 2.0 }
+    #
+    # @example Duration factor
+    #   previous = { grade: 0, duration: 1.0 }.extend(GDV)
+    #   gdvd = { factor_duration: 2 }.extend(GDVd)
+    #   gdv = gdvd.to_gdv(scale, previous: previous)
+    #   # => { grade: 0, duration: 2.0 }
     def to_gdv(scale, previous:)
       r = previous.clone.delete_if {|k,_| !GDV::NaturalKeys.include?(k)}.extend GDV
 
@@ -109,6 +261,18 @@ module Musa::Datasets
       r
     end
 
+    # Normalizes chromatic pitch to scale note.
+    #
+    # Converts arbitrary grade + sharps to closest scale note representation.
+    # If chromatic, returns background note + chromatic alteration.
+    #
+    # @param scale [Musa::Scales::Scale] reference scale
+    # @param grade [Integer] scale degree (wide grade)
+    # @param sharps [Integer] chromatic alteration
+    #
+    # @return [Array(Integer, Integer)] [normalized_grade, normalized_sharps]
+    #
+    # @api private
     private def normalize_to_scale(scale, grade, sharps)
       note = scale[grade].sharp(sharps)
       background = note.background_note
@@ -120,6 +284,43 @@ module Musa::Datasets
       end
     end
 
+    # Converts to Neuma delta notation string.
+    #
+    # Neuma delta format uses special notation for changes:
+    #
+    #     ([grade_delta] [octave_delta] [duration_delta] [velocity_delta] [modifiers...])
+    #
+    # - **Grade delta**: "+2" or "-2" (semitone change)
+    # - **Sharp delta**: "+#" or "-_" (chromatic change)
+    # - **Octave delta**: "+o1" or "-o1" (octave change)
+    # - **Duration delta**: "+0.5", "-0.5", or "*2" (duration change)
+    # - **Velocity delta**: "+f" or "-f" (dynamics change by f's)
+    #
+    # @return [String] Neuma delta notation
+    #
+    # @example Delta grade
+    #   gdvd = { delta_grade: 2 }.extend(GDVd)
+    #   gdvd.base_duration = 1/4r
+    #   gdvd.to_neuma  # => "(+2)"
+    #
+    # @example Multiple deltas
+    #   gdvd = { delta_grade: -2, delta_velocity: 1 }.extend(GDVd)
+    #   gdvd.base_duration = 1/4r
+    #   gdvd.to_neuma  # => "(-2 +f)"
+    #
+    # @example Duration factor
+    #   gdvd = { factor_duration: 2 }.extend(GDVd)
+    #   gdvd.base_duration = 1/4r
+    #   gdvd.to_neuma  # => "(. *2)"
+    #
+    # @example Chromatic change
+    #   gdvd = { delta_sharps: 1 }.extend(GDVd)
+    #   gdvd.to_neuma  # => "(+#)"
+    #
+    # @example Absolute values
+    #   gdvd = { abs_grade: 0, abs_duration: 1.0 }.extend(GDVd)
+    #   gdvd.base_duration = 1/4r
+    #   gdvd.to_neuma  # => "(0 4)"
     def to_neuma
       @base_duration ||= Rational(1,4)
 

data/lib/musa-dsl/datasets/helper.rb

@@ -1,19 +1,86 @@
 module Musa::Datasets
+  # Helper utilities for dataset formatting and string generation.
+  #
+  # Helper provides utility methods for converting datasets to string
+  # representations, particularly for the Neuma notation format.
+  #
+  # These methods handle:
+  #
+  # - Sign formatting (+/-)
+  # - Velocity to dynamics conversion
+  # - Modifier parameter formatting
+  #
+  # @api private
   module Helper
     private
 
+    # Returns '+' for non-negative numbers, empty string for negative.
+    #
+    # Used for formatting delta values in Neuma notation.
+    #
+    # @param x [Numeric] number to check
+    # @return [String] '+' or ''
+    #
+    # @example
+    #   positive_sign_of(5)   # => '+'
+    #   positive_sign_of(-3)  # => ''
+    #
+    # @api private
     def positive_sign_of(x)
       x >= 0 ? '+' : ''
     end
 
+    # Returns '+', '+', or '-' based on number's sign.
+    #
+    # @param x [Numeric] number to check
+    # @return [String] '+' (positive), '+' (zero), or '-' (negative)
+    #
+    # @example
+    #   sign_of(5)   # => '+'
+    #   sign_of(0)   # => '+'
+    #   sign_of(-3)  # => '-'
+    #
+    # @api private
     def sign_of(x)
       '++-'[x <=> 0]
     end
 
+    # Converts numeric velocity to dynamics marking.
+    #
+    # Maps velocity values (-5 to +4) to standard dynamics markings.
+    # Range: ppp (-5) to fff (+4), centered at mf (0).
+    #
+    # @param x [Integer] velocity value
+    # @return [String] dynamics marking
+    #
+    # @example
+    #   velocity_of(-5)  # => 'ppp'
+    #   velocity_of(0)   # => 'mf'
+    #   velocity_of(4)   # => 'fff'
+    #
+    # @api private
     def velocity_of(x)
       %w[ppp pp p mp mf f ff fff][x + 3]
     end
 
+    # Formats modifier with parameters for Neuma notation.
+    #
+    # Converts modifier keys and their parameters into Neuma string format.
+    #
+    # @param modificator [Symbol] modifier key name
+    # @param parameter_or_parameters [Boolean, Array, Object] modifier parameters
+    # @return [String] formatted modifier string
+    #
+    # @example Boolean modifier (flag)
+    #   modificator_string(:staccato, true)  # => 'staccato'
+    #
+    # @example Single parameter
+    #   modificator_string(:pedal, 'down')  # => 'pedal("down")'
+    #
+    # @example Multiple parameters
+    #   modificator_string(:bend, [2, 'up'])  # => 'bend(2, "up")'
+    #
+    # @api private
     def modificator_string(modificator, parameter_or_parameters)
       case parameter_or_parameters
       when true
@@ -27,6 +94,14 @@ module Musa::Datasets
 
     private
 
+    # Converts parameter to string representation.
+    #
+    # Handles different parameter types for Neuma notation.
+    #
+    # @param parameter [String, Numeric, Symbol] parameter value
+    # @return [String] formatted parameter
+    #
+    # @api private
     def parameter_to_string(parameter)
       case parameter
       when String

data/lib/musa-dsl/datasets/p.rb

@@ -5,9 +5,113 @@ require_relative '../series'
 require_relative '../sequencer'
 
 module Musa::Datasets
+  # Point series: sequential points in time with durations.
+  #
+  # P (Point series) represents sequential points in time as arrays with alternating
+  # structure: [point, duration, point, duration, point, ...].
+  #
+  # ## Structure
+  #
+  # The array alternates between points and durations:
+  #
+  #     [point₀, duration₀, point₁, duration₁, point₂]
+  #
+  # - **Points** (odd positions): Any data (numbers, hashes, complex structures, etc.)
+  # - **Durations** (even positions): Time between points (numbers)
+  # - **Last point**: Final point has no duration (sequence end)
+  #
+  # This compact format efficiently represents timed sequences without
+  # repeating time information.
+  #
+  # ## Conversions
+  #
+  # P can be converted to two different representations:
+  #
+  # ### 1. Timed Series (to_timed_serie)
+  #
+  # Converts to series of {AbsTimed} events with absolute time and value.
+  # Each value gets a timestamp based on cumulative durations.
+  #
+  #     p = [60, 4, 64, 8, 67].extend(P)
+  #     serie = p.to_timed_serie
+  #     # Yields:
+  #     # { time: 0, value: 60 }
+  #     # { time: 1.0, value: 64 }  (4 * base_duration = 1.0)
+  #     # { time: 3.0, value: 67 }  (8 * base_duration = 2.0)
+  #
+  # ### 2. Parameter Segment Series (to_ps_serie)
+  #
+  # Converts to series of {PS} (Parameter Segment) objects representing
+  # continuous changes between consecutive points.
+  #
+  #     p = [60, 4, 64, 8, 67].extend(P)
+  #     serie = p.to_ps_serie
+  #     # Yields PS objects:
+  #     # { from: 60, to: 64, duration: 1.0, right_open: true }
+  #     # { from: 64, to: 67, duration: 2.0, right_open: false }
+  #
+  # ## Point Transformation
+  #
+  # The {#map} method transforms points while preserving durations:
+  #
+  #     p = [60, 4, 64, 8, 67].extend(P)
+  #     p2 = p.map { |point| point + 12 }
+  #     # => [72, 4, 76, 8, 79]
+  #     # Durations unchanged, points transformed
+  #
+  # @example Basic point series (MIDI pitches)
+  #   # MIDI pitches with durations in quarter notes
+  #   p = [60, 4, 64, 8, 67].extend(Musa::Datasets::P)
+  #   # 60 (C4) for 4 quarters → 64 (E4) for 8 quarters → 67 (G4)
+  #
+  # @example Hash points (complex data structures)
+  #   p = [
+  #     { pitch: 60, velocity: 64 }, 4,
+  #     { pitch: 64, velocity: 80 }, 8,
+  #     { pitch: 67, velocity: 64 }
+  #   ].extend(Musa::Datasets::P)
+  #
+  # @example Convert to timed serie
+  #   p = [60, 4, 64, 8, 67].extend(Musa::Datasets::P)
+  #   serie = p.to_timed_serie(base_duration: 1/4r)
+  #   # base_duration: quarter note = 1/4 beat
+  #
+  # @example Start at specific time
+  #   serie = p.to_timed_serie(time_start: 10)
+  #   # First event at time 10
+  #
+  # @example Start time from component
+  #   p = [{ time: 100, pitch: 60 }, 4, { time: 200, pitch: 64 }].extend(P)
+  #   serie = p.to_timed_serie(time_start_component: :time)
+  #   # First event at time 100 (from first point's :time)
+  #
+  # @example Transform points
+  #   p = [60, 4, 64, 8, 67].extend(Musa::Datasets::P)
+  #   p2 = p.map { |point| point + 12 }
+  #   # Transform each point (e.g., transpose pitches up one octave)
+  #
+  # @see PS Parameter segments
+  # @see AbsTimed Timed events
+  # @see Dataset Parent dataset module
   module P
     include Dataset
 
+    # Converts to series of parameter segments.
+    #
+    # Creates {PS} objects representing continuous changes from each point
+    # to the next. Useful for glissandi, parameter sweeps, or any continuous
+    # interpolation between points.
+    #
+    # @param base_duration [Rational] duration unit multiplier (default: 1/4r)
+    #   Durations in P are multiplied by this to get actual time
+    #
+    # @return [Musa::Series::Serie<PS>] series of parameter segments
+    #
+    # @example Create parameter segments
+    #   p = [60, 4, 64, 8, 67].extend(P)
+    #   serie = p.to_ps_serie
+    #   segment1 = serie.next_value
+    #   # => { from: 60, to: 64, duration: 1.0, right_open: true }
     def to_ps_serie(base_duration: nil)
       base_duration ||= 1/4r # TODO review incoherence between neumalang 1/4r base duration for quarter notes and general 1r size of bar
 
@@ -22,6 +126,33 @@ module Musa::Datasets
       end
     end
 
+    # Converts to series of timed events (AbsTimed).
+    #
+    # Creates series yielding {AbsTimed} events with absolute time and value.
+    # Each value is emitted at its calculated time point based on cumulative durations.
+    #
+    # @param time_start [Numeric] starting time offset (default: 0)
+    # @param time_start_component [Symbol] key in first value to use as time offset
+    #   If provided, adds first[time_start_component] to time_start
+    # @param base_duration [Rational] duration unit multiplier (default: 1/4r)
+    #
+    # @return [PtoTimedSerie] series of timed events
+    #
+    # @example Basic timed serie
+    #   p = [60, 4, 64, 8, 67].extend(P)
+    #   serie = p.to_timed_serie
+    #   serie.next_value  # => { time: 0, value: 60 }
+    #   serie.next_value  # => { time: 1.0, value: 64 }
+    #   serie.next_value  # => { time: 3.0, value: 67 }
+    #
+    # @example Custom start time
+    #   serie = p.to_timed_serie(time_start: 10)
+    #   # First event at time 10
+    #
+    # @example Start time from component
+    #   p = [{ time: 100, pitch: 60 }, 4, { pitch: 64 }].extend(P)
+    #   serie = p.to_timed_serie(time_start_component: :time)
+    #   # First event at time 100
     def to_timed_serie(time_start: nil, time_start_component: nil, base_duration: nil)
       time_start ||= 0r
       time_start += self.first[time_start_component] if time_start_component
@@ -31,11 +162,30 @@ module Musa::Datasets
       PtoTimedSerie.new(self, base_duration, time_start)
     end
 
+    # Maps over points, preserving durations.
+    #
+    # Transforms each point (odd positions) using the block while
+    # keeping durations (even positions) unchanged.
+    #
+    # @yieldparam point [Object] each point in the series
+    # @yieldreturn [Object] transformed point
+    #
+    # @return [P] new P with transformed points
+    #
+    # @example Transform points (e.g., transpose pitches)
+    #   p = [60, 4, 64, 8, 67].extend(P)
+    #   p.map { |point| point + 12 }
+    #   # => [72, 4, 76, 8, 79]
+    #
+    # @example Transform hash points
+    #   p = [{ pitch: 60 }, 4, { pitch: 64 }].extend(P)
+    #   p.map { |point| point.merge(velocity: 80) }
+    #   # Adds velocity to each point
     def map(&block)
       i = 0
       clone.map! do |element|
-        # Process with block only the values (values are the alternating elements because P
-        # structure is <value> <duration> <value> <duration> <value>)
+        # Process with block only the points (points are the alternating elements because P
+        # structure is <point> <duration> <point> <duration> <point>)
         #
         if (i += 1) % 2 == 1
           block.call(element)
@@ -45,9 +195,26 @@ module Musa::Datasets
       end
     end
 
+    # Series adapter for P to AbsTimed conversion.
+    #
+    # PtoTimedSerie is a {Musa::Series::Serie} that converts a {P} (point series)
+    # into a series of {AbsTimed} events. It reads the alternating point/duration
+    # structure and emits timed events.
+    #
+    # This class is created by {P#to_timed_serie} and should not be instantiated
+    # directly.
+    #
+    # @api private
     class PtoTimedSerie
       include Musa::Series::Serie.base
 
+      # Creates new timed serie adapter.
+      #
+      # @param origin [P] source point series
+      # @param base_duration [Rational] duration unit multiplier
+      # @param time_start [Numeric] starting time offset
+      #
+      # @api private
       def initialize(origin, base_duration, time_start)
         @origin = origin
         @base_duration = base_duration
@@ -58,8 +225,16 @@ module Musa::Datasets
         mark_as_prototype!
       end
 
+      # Source point series.
+      # @return [P]
       attr_accessor :origin
+
+      # Duration unit multiplier.
+      # @return [Rational]
       attr_accessor :base_duration
+
+      # Starting time offset.
+      # @return [Numeric]
       attr_accessor :time_start
 
       private def _init

data/lib/musa-dsl/datasets/packed-v.rb

@@ -2,9 +2,100 @@ require_relative 'e'
 require_relative 'v'
 
 module Musa::Datasets
+  # Hash-based dataset with array conversion.
+  #
+  # PackedV (Packed Value) represents datasets stored as hashes (named key-value pairs).
+  # Extends {AbsI} for absolute indexed events.
+  #
+  # ## Purpose
+  #
+  # PackedV provides named key-value storage for musical data and conversion
+  # to indexed arrays ({V}). This is useful for:
+  #
+  # - Semantic naming of values (pitch, duration, velocity)
+  # - Sparse data (only store non-default values)
+  # - Converting between hash and array representations
+  # - Serialization to readable formats
+  #
+  # ## Conversion to V
+  #
+  # The {#to_V} method converts hashes to arrays using a mapper that
+  # defines the correspondence between hash keys and array positions.
+  #
+  # ### Array Mapper
+  #
+  # Array mapper defines the order of keys in resulting array.
+  # Position i contains value for key mapper[i].
+  #
+  #     pv = { pitch: 60, duration: 1.0 }.extend(Musa::Datasets::PackedV)
+  #     v = pv.to_V([:pitch, :duration, :velocity])
+  #     # => [60, 1.0, nil]
+  #     # velocity missing, becomes nil
+  #
+  # - Missing keys become `nil` in array
+  #
+  # ### Hash Mapper
+  #
+  # Hash mapper defines both key order (keys) and default values (values).
+  # Position i contains value for key mapper.keys[i], using mapper.values[i]
+  # as default if key is missing or value is nil.
+  #
+  #     pv = { pitch: 60 }.extend(Musa::Datasets::PackedV)
+  #     v = pv.to_V({ pitch: 60, duration: 1.0, velocity: 64 })
+  #     # => [60, 1.0, 64]
+  #     # duration and velocity use defaults
+  #
+  # Defaults fill in missing or nil values.
+  #
+  # @example Basic hash to array conversion
+  #   pv = { pitch: 60, duration: 1.0, velocity: 64 }.extend(Musa::Datasets::PackedV)
+  #   v = pv.to_V([:pitch, :duration, :velocity])
+  #   # => [60, 1.0, 64]
+  #
+  # @example Missing keys become nil (array mapper)
+  #   pv = { a: 1, c: 3 }.extend(Musa::Datasets::PackedV)
+  #   v = pv.to_V([:c, :b, :a])
+  #   # => [3, nil, 1]
+  #   # b missing, becomes nil
+  #
+  # @example Hash mapper with defaults
+  #   pv = { a: 1, b: nil, c: 3 }.extend(Musa::Datasets::PackedV)
+  #   v = pv.to_V({ c: 100, b: 200, a: 300, d: 400 })
+  #   # => [3, 200, 1, 400]
+  #   # b nil → uses default 200
+  #   # d missing → uses default 400
+  #
+  # @example Partial mapper (fewer keys in mapper)
+  #   pv = { a: 1, b: 2, c: 3 }.extend(Musa::Datasets::PackedV)
+  #   v = pv.to_V([:c, :b])
+  #   # => [3, 2]
+  #   # Only c and b extracted
+  #
+  # @example Key order matters
+  #   pv = { a: 1, b: 2, c: 3 }.extend(Musa::Datasets::PackedV)
+  #   v = pv.to_V([:c, :b, :a])
+  #   # => [3, 2, 1]
+  #
+  # @see V Array-based dataset (inverse)
+  # @see AbsI Parent absolute indexed module
   module PackedV
     include AbsI
 
+    # Converts packed hash to array (V).
+    #
+    # @param mapper [Array<Symbol>, Hash{Symbol => Object}] key mapping
+    #   - Array: maps keys to indices (order matters)
+    #   - Hash: maps keys (keys) to indices with defaults (values)
+    #
+    # @return [V] array dataset
+    #
+    # @raise [ArgumentError] if mapper is not Array or Hash
+    #
+    # @example Array mapper
+    #   pv.to_V([:pitch, :duration, :velocity])
+    #
+    # @example Hash mapper with defaults
+    #   pv.to_V({ pitch: 60, duration: 1.0, velocity: 64 })
     def to_V(mapper)
       case mapper
       when Hash