vizcore 1.1.0 → 1.2.0

data/lib/vizcore/dsl/layer_builder.rb

@@ -2,7 +2,11 @@
 
 require_relative "mapping_transform_builder"
 require_relative "reaction_builder"
+require_relative "../deep_copy"
+require_relative "../layer_catalog"
 require_relative "../shape"
+require_relative "color_helpers"
+require_relative "layout_helpers"
 
 module Vizcore
   module DSL
@@ -11,7 +15,9 @@ module Vizcore
       NO_ARGUMENT = Object.new.freeze
       SHAPE_SCHEMA_VERSION = 2
       MAPPING_SOURCE_KINDS = %i[
-        amplitude frequency_band fft_spectrum onset kick snare hihat beat beat_confidence beat_pulse beat_count bpm
+        amplitude peak frequency_band frequency_band_peak fft_spectrum onset kick snare hihat beat beat_confidence beat_pulse beat_count bpm
+        beat_phase beat_2 beat_4 beat_8 beat_triplet triplet bar_phase bar_count phrase_count bpm_confidence
+        spectral_centroid spectral_rolloff spectral_flatness spectral_flux zero_crossing_rate global lfo adsr envelope
       ].freeze
       PATH_DEFAULT_DETAIL = 32
       PATH_MIN_DETAIL = 4
@@ -30,6 +36,9 @@ module Vizcore
       }.freeze
       SHAPE_STYLE_KEYS = Vizcore::Shape::STYLE_KEYS
       SHAPE_TRANSFORM_KEYS = %i[translate rotate rotation scale origin].freeze
+      STRICT_PARAM_ALLOWLIST = %i[
+        custom_shape_controls custom_shapes glsl_source group origin rotate scale translate
+      ].freeze
 
       # Reference to an already declared shape, used by `map ... to: shape(:id).radius`.
       class ShapeReference
@@ -52,9 +61,13 @@ module Vizcore
       # @param name [Symbol, String] layer identifier
       # @param styles [Hash] reusable layer parameter styles
       # @param defaults [Hash] default params applied before layer-specific values
-      def initialize(name:, styles: {}, defaults: {})
+      # @param strict [Boolean] true when unknown layer params should fail
+      # @param mapping_presets [Hash] reusable mapping presets
+      def initialize(name:, styles: {}, defaults: {}, mapping_presets: {}, strict: false)
         @name = name.to_sym
         @styles = styles
+        @mapping_presets = mapping_presets
+        @strict = !!strict
         @type = nil
         @shader = nil
         @glsl = nil
@@ -65,6 +78,9 @@ module Vizcore
         @shape_group_stack = [{}]
       end
 
+      include ColorHelpers
+      include LayoutHelpers
+
       # Evaluate a layer block.
       #
       # @yield Layer DSL methods
@@ -522,7 +538,12 @@ module Vizcore
       # @return [ShapeReference]
       def shape(id)
         key = id.to_sym
-        index = @shape_index_by_id.fetch(key) { raise ArgumentError, "unknown shape id: #{key.inspect}" }
+        index = @shape_index_by_id.fetch(key) do
+          suggestion_message = shape_id_suggestions(key)
+          message = "unknown shape id: #{key.inspect}"
+          message = "#{message}. Did you mean: #{suggestion_message}" unless suggestion_message.empty?
+          raise ArgumentError, message
+        end
         ShapeReference.new("shapes.#{index}")
       end
 
@@ -567,6 +588,17 @@ module Vizcore
         @params[:palette] = normalize_palette(colors)
       end
 
+      # Append one post effect to this layer's post effect chain.
+      #
+      # @param name [Symbol, String] effect key
+      # @return [Symbol]
+      def post(name)
+        raise ArgumentError, "post expects a symbol or string" unless name
+
+        @params[:post_effects] ||= []
+        @params[:post_effects] << name.to_sym
+      end
+
       # Apply a named style by merging its params into this layer.
       #
       # @param name [Symbol, String] style identifier
@@ -636,6 +668,17 @@ module Vizcore
         end
       end
 
+      # Apply a named mapping preset to this layer.
+      #
+      # @param name [Symbol, String] mapping preset identifier
+      # @raise [ArgumentError] when the preset is unknown
+      # @return [void]
+      def use_mapping(name)
+        preset_name = name.to_sym
+        preset = @mapping_presets.fetch(preset_name) { raise ArgumentError, "unknown mapping preset: #{preset_name}" }
+        preset.each { |mapping| @mappings << deep_dup(mapping) }
+      end
+
       # High-level mapping DSL for describing audio reactions inside a layer.
       #
       # @param source_value [Hash, Symbol, String] analysis source descriptor
@@ -663,42 +706,82 @@ module Vizcore
         mapping_source(:amplitude)
       end
 
+      # @return [Hash] source descriptor for absolute sample peak level
+      def peak
+        mapping_source(:peak)
+      end
+
       # @param name [Symbol, String] band key (`sub`, `low`, `mid`, `high`)
       # @return [Hash] source descriptor for a frequency band
       def frequency_band(name)
         mapping_source(:frequency_band, band: name.to_sym)
       end
 
+      # @return [Hash] source descriptor for a held frequency-band peak
+      def frequency_band_peak(name)
+        mapping_source(:frequency_band_peak, band: name.to_sym)
+      end
+
       # @return [Hash] source descriptor for the sub-bass frequency band
       def sub
         frequency_band(:sub)
       end
 
+      # @return [Hash] source descriptor for the held sub-bass peak
+      def sub_peak
+        frequency_band_peak(:sub)
+      end
+
       # @return [Hash] source descriptor for the low/bass frequency band
       def low
         frequency_band(:low)
       end
 
+      # @return [Hash] source descriptor for the held low/bass peak
+      def low_peak
+        frequency_band_peak(:low)
+      end
+
       # @return [Hash] source descriptor for the low/bass frequency band
       def bass
         frequency_band(:low)
       end
 
+      # @return [Hash] source descriptor for the held low/bass peak
+      def bass_peak
+        frequency_band_peak(:low)
+      end
+
       # @return [Hash] source descriptor for the mid frequency band
       def mid
         frequency_band(:mid)
       end
 
+      # @return [Hash] source descriptor for the held mid peak
+      def mid_peak
+        frequency_band_peak(:mid)
+      end
+
       # @return [Hash] source descriptor for the high frequency band
       def high
         frequency_band(:high)
       end
 
+      # @return [Hash] source descriptor for the held high peak
+      def high_peak
+        frequency_band_peak(:high)
+      end
+
       # @return [Hash] source descriptor for the high/treble frequency band
       def treble
         frequency_band(:high)
       end
 
+      # @return [Hash] source descriptor for the held high/treble peak
+      def treble_peak
+        frequency_band_peak(:high)
+      end
+
       # @return [Hash] source descriptor for FFT spectrum array
       def fft_spectrum
         mapping_source(:fft_spectrum)
@@ -757,13 +840,138 @@ module Vizcore
         mapping_source(:beat_count)
       end
 
+      # @return [Hash] source descriptor for 0.0..1.0 phase within the current beat
+      def beat_phase
+        mapping_source(:beat_phase)
+      end
+
+      # @return [Hash] source descriptor for half-beat subdivision pulses
+      def beat_2
+        mapping_source(:beat_2)
+      end
+
+      # @return [Hash] source descriptor for quarter-beat subdivision pulses
+      def beat_4
+        mapping_source(:beat_4)
+      end
+
+      # @return [Hash] source descriptor for eighth-beat subdivision pulses
+      def beat_8
+        mapping_source(:beat_8)
+      end
+
+      # @return [Hash] source descriptor for triplet subdivision pulses
+      def beat_triplet
+        mapping_source(:beat_triplet)
+      end
+
+      # @return [Hash] source descriptor for triplet subdivision pulses
+      def triplet
+        mapping_source(:beat_triplet)
+      end
+
+      # @return [Hash] source descriptor for 0.0..1.0 phase within the current 4-beat bar
+      def bar_phase
+        mapping_source(:bar_phase)
+      end
+
+      # @return [Hash] source descriptor for completed 4-beat bars
+      def bar_count(value = NO_ARGUMENT)
+        return @params[:bar_count] = Integer(value) unless value.equal?(NO_ARGUMENT)
+
+        mapping_source(:bar_count)
+      end
+
+      # @return [Hash] source descriptor for completed 8-bar phrases
+      def phrase_count
+        mapping_source(:phrase_count)
+      end
+
       # @return [Hash] source descriptor for estimated BPM
       def bpm
         mapping_source(:bpm)
       end
 
+      # @return [Hash] source descriptor for tempo estimator confidence
+      def bpm_confidence
+        mapping_source(:bpm_confidence)
+      end
+
+      # @return [Hash] source descriptor for spectral centroid in Hz
+      def spectral_centroid
+        mapping_source(:spectral_centroid)
+      end
+
+      # @return [Hash] source descriptor for spectral rolloff in Hz
+      def spectral_rolloff
+        mapping_source(:spectral_rolloff)
+      end
+
+      # @return [Hash] source descriptor for spectral flatness
+      def spectral_flatness
+        mapping_source(:spectral_flatness)
+      end
+
+      # @return [Hash] source descriptor for positive spectrum delta
+      def spectral_flux
+        mapping_source(:spectral_flux)
+      end
+
+      # @return [Hash] source descriptor for time-domain zero crossing rate
+      def zero_crossing_rate
+        mapping_source(:zero_crossing_rate)
+      end
+
+      # @param name [Symbol, String] runtime global value name
+      # @return [Hash] source descriptor for mutable runtime globals
+      def global(name)
+        mapping_source(:global, name: name.to_sym)
+      end
+
+      # @param wave [Symbol, String] one of `sine`, `triangle`, `saw`, `square`
+      # @param rate [Numeric] cycles per second
+      # @param phase [Numeric] phase offset in cycles
+      # @return [Hash] source descriptor for a time-based low-frequency oscillator
+      def lfo(wave = :sine, rate: 1.0, phase: 0.0)
+        mapping_source(:lfo, wave: wave.to_sym, rate: Float(rate), phase: Float(phase))
+      rescue ArgumentError, TypeError
+        raise ArgumentError, "lfo rate and phase must be numeric"
+      end
+
+      # @param source [Symbol, Hash] source to trigger the envelope
+      # @param attack [Numeric] seconds from 0.0 to peak
+      # @param decay [Numeric] seconds from peak to sustain
+      # @param sustain [Numeric] sustain gain once decay is complete (0.0..1.0)
+      # @param release [Numeric] seconds from sustain to 0.0
+      # @param threshold [Numeric] value threshold that starts attack
+      # @param peak [Numeric] peak gain multiplier
+      # @return [Hash] source descriptor for an ADSR envelope
+      def adsr(source = :kick, attack: 0.02, decay: 0.08, sustain: 0.7, release: 0.16, threshold: 0.0, peak: 1.0)
+        source_value = source.nil? ? { kind: :kick } : normalize_source(source)
+        mapping_source(
+          :adsr,
+          source: source_value,
+          attack: normalize_non_negative_float(attack, :attack),
+          decay: normalize_non_negative_float(decay, :decay),
+          sustain: clamp(normalize_float(sustain, :sustain), 0.0, 1.0),
+          release: normalize_non_negative_float(release, :release),
+          threshold: normalize_float(threshold, :threshold),
+          peak: normalize_float(peak, :peak)
+        )
+      end
+
+      # Alias for ADSR envelope mapping source.
+      #
+      # @param source [Symbol, Hash] source to trigger the envelope
+      # @param options [Numeric] envelope timing and shaping values
+      # @return [Hash] source descriptor for a general envelope
+      def envelope(source = :kick, **options)
+        adsr(source, **options)
+      end
+
       # @return [Hash] serialized layer payload
       def to_h
+        validate_strict_params! if @strict
         layer = {
           name: @name,
           type: resolved_type,
@@ -1322,16 +1530,7 @@ module Vizcore
       end
 
       def deep_dup(value)
-        case value
-        when Hash
-          value.each_with_object({}) do |(key, entry), output|
-            output[key] = deep_dup(entry)
-          end
-        when Array
-          value.map { |entry| deep_dup(entry) }
-        else
-          value
-        end
+        Vizcore::DeepCopy.copy(value)
       end
 
       def evaluate_transform_block(initial_options, &block)
@@ -1365,19 +1564,26 @@ module Vizcore
         raise ArgumentError, "param min must be less than or equal to max"
       end
 
-      def normalize_transform(gain: nil, range: nil, min: nil, max: nil, curve: nil, attack: nil, release: nil, deadzone: nil)
+      def normalize_transform(gain: nil, range: nil, min: nil, max: nil, curve: nil, attack: nil, release: nil, deadzone: nil, threshold: nil, hysteresis: nil, hold: nil, decay: nil, cooldown: nil, one_shot: nil, as: nil)
         range_min, range_max = normalize_range(range, context: "mapping")
         min = range_min if min.nil?
         max = range_max if max.nil?
 
         output = {}
         output[:deadzone] = normalize_non_negative_float(deadzone, :deadzone) unless deadzone.nil?
+        output[:as] = normalize_mapping_mode(as) unless as.nil?
+        output[:threshold] = normalize_float(threshold, :threshold) unless threshold.nil?
+        output[:hysteresis] = normalize_non_negative_float(hysteresis, :hysteresis) unless hysteresis.nil?
         output[:gain] = normalize_float(gain, :gain) unless gain.nil?
         output[:min] = normalize_float(min, :min) unless min.nil?
         output[:max] = normalize_float(max, :max) unless max.nil?
         output[:curve] = normalize_curve(curve) unless curve.nil?
         output[:attack] = clamp(normalize_float(attack, :attack), 0.0, 1.0) unless attack.nil?
         output[:release] = clamp(normalize_float(release, :release), 0.0, 1.0) unless release.nil?
+        output[:hold] = normalize_non_negative_float(hold, :hold) unless hold.nil?
+        output[:decay] = clamp(normalize_float(decay, :decay), 0.0, 1.0) unless decay.nil?
+        output[:cooldown] = normalize_non_negative_float(cooldown, :cooldown) unless cooldown.nil?
+        output[:one_shot] = !!one_shot unless one_shot.nil?
         output
       end
 
@@ -1419,11 +1625,30 @@ module Vizcore
 
       def normalize_curve(value)
         curve = value.to_sym
-        return curve if %i[linear sqrt square ease_out].include?(curve)
+        return curve if %i[linear sqrt square ease_out ease_in ease_in_out smoothstep exp log step].include?(curve)
 
         raise ArgumentError, "unsupported mapping curve: #{value.inspect}"
       end
 
+      def normalize_mapping_mode(value)
+        mode = value.to_sym
+        return mode if %i[continuous trigger].include?(mode)
+
+        raise ArgumentError, "unsupported mapping mode: #{value.inspect}"
+      end
+
+      def validate_strict_params!
+        unknown = @params.keys.map(&:to_sym) - strict_allowed_params
+        return if unknown.empty?
+
+        raise ArgumentError, "layer #{@name} has unknown params in strict mode: #{unknown.sort.join(', ')}"
+      end
+
+      def strict_allowed_params
+        catalog_params = Vizcore::LayerCatalog.params_for(resolved_type).keys
+        (catalog_params + @param_schema.keys + STRICT_PARAM_ALLOWLIST).map(&:to_sym).uniq
+      end
+
       def clamp(value, min, max)
         [[value, min].max, max].min
       end
@@ -1434,6 +1659,44 @@ module Vizcore
           **options
         }
       end
+
+      def shape_id_suggestions(key)
+        return "" if @shape_index_by_id.empty?
+
+        candidates = @shape_index_by_id.keys
+          .map do |shape_id|
+            [shape_id, levenshtein_distance(shape_id.to_s, key.to_s)]
+          end
+          .select { |_, distance| distance <= 3 }
+          .sort_by { |shape_id, distance| [distance, shape_id.to_s] }
+          .first(3)
+
+        return "" if candidates.empty?
+
+        candidates.map { |shape_id, _| shape_id.inspect }.join(", ")
+      end
+
+      def levenshtein_distance(a, b)
+        prev = (0..b.length).to_a
+        b_chars = b.bytes
+        a_bytes = a.bytes
+
+        a_bytes.each_with_index do |codepoint_a, index_a|
+          current = [index_a + 1]
+          b_chars.each_with_index do |codepoint_b, index_b|
+            cost = codepoint_a == codepoint_b ? 0 : 1
+            current << [
+              current[index_b] + 1,
+              prev[index_b + 1] + 1,
+              prev[index_b] + cost
+            ].min
+          end
+
+          prev = current
+        end
+
+        prev[b.length]
+      end
     end
   end
 end

data/lib/vizcore/dsl/layer_group_builder.rb

@@ -1,17 +1,24 @@
 # frozen_string_literal: true
 
 require_relative "layer_builder"
+require_relative "color_helpers"
 
 module Vizcore
   module DSL
     # Collects related layers and applies shared layer parameters.
     class LayerGroupBuilder
+      include ColorHelpers
+
       # @param name [Symbol, String] group identifier stored on nested layer params
       # @param styles [Hash] reusable layer parameter styles
+      # @param mapping_presets [Hash] reusable layer mapping presets
       # @param defaults [Hash] scene defaults already applied before group params
-      def initialize(name:, styles: {}, defaults: {})
+      # @param strict [Boolean] true when unknown layer params should fail
+      def initialize(name:, styles: {}, defaults: {}, mapping_presets: {}, strict: false)
         @name = name.to_sym
         @styles = styles
+        @mapping_presets = mapping_presets
+        @strict = !!strict
         @params = deep_dup(defaults)
         @layers = []
       end
@@ -31,7 +38,7 @@ module Vizcore
       # @yield Layer definition block
       # @return [void]
       def layer(name, &block)
-        builder = LayerBuilder.new(name: name, styles: @styles, defaults: layer_defaults)
+        builder = LayerBuilder.new(name: name, styles: @styles, mapping_presets: @mapping_presets, defaults: layer_defaults, strict: @strict)
         builder.evaluate(&block)
         @layers << builder.to_h
       end
@@ -96,16 +103,7 @@ module Vizcore
       end
 
       def deep_dup(value)
-        case value
-        when Hash
-          value.each_with_object({}) do |(key, entry), output|
-            output[key] = deep_dup(entry)
-          end
-        when Array
-          value.map { |entry| deep_dup(entry) }
-        else
-          value
-        end
+        Vizcore::DeepCopy.copy(value)
       end
     end
   end