vizcore 0.1.0 → 1.0.0

data/lib/vizcore/dsl/layer_builder.rb

@@ -1,16 +1,28 @@
 # frozen_string_literal: true
 
+require_relative "mapping_transform_builder"
+require_relative "reaction_builder"
+
 module Vizcore
   module DSL
     # Builder for one render layer in a scene.
     class LayerBuilder
+      NO_ARGUMENT = Object.new.freeze
+      MAPPING_SOURCE_KINDS = %i[
+        amplitude frequency_band fft_spectrum onset kick snare hihat beat beat_confidence beat_pulse beat_count bpm
+      ].freeze
+
       # @param name [Symbol, String] layer identifier
-      def initialize(name:)
+      # @param styles [Hash] reusable layer parameter styles
+      # @param defaults [Hash] default params applied before layer-specific values
+      def initialize(name:, styles: {}, defaults: {})
         @name = name.to_sym
+        @styles = styles
         @type = nil
         @shader = nil
         @glsl = nil
-        @params = {}
+        @params = deep_dup(defaults)
+        @param_schema = {}
         @mappings = []
       end
 
@@ -29,10 +41,16 @@ module Vizcore
         @type = value.to_sym
       end
 
-      # @param value [Symbol, String] built-in shader key
+      # @param value [Symbol, String] built-in shader key or custom GLSL path
+      # @param reload [Boolean, nil] accepted for custom shader path compatibility
       # @return [Symbol]
-      def shader(value)
-        @shader = value.to_sym
+      def shader(value, reload: nil)
+        if shader_path?(value)
+          @glsl = value.to_s
+          @params[:shader_reload] = !!reload unless reload.nil?
+        else
+          @shader = value.to_sym
+        end
         @type ||= :shader
       end
 
@@ -43,6 +61,49 @@ module Vizcore
         @type ||= :shader
       end
 
+      # @param path [String, Pathname] asset file path used by media-like layers
+      # @return [String]
+      def file(path)
+        @params[:file] = path.to_s
+      end
+
+      # Declare a 2D circle/ring primitive for a shape layer.
+      #
+      # @param options [Hash] shape params such as `count`, `radius`, `x`, and `y`
+      # @yield optional block evaluated in the shape context
+      # @return [Hash]
+      def circle(**options, &block)
+        build_shape(:circle, options, &block)
+      end
+
+      # Declare a 2D line primitive for a shape layer.
+      #
+      # @param options [Hash] shape params such as `x1`, `y1`, `x2`, and `y2`
+      # @yield optional block evaluated in the shape context
+      # @return [Hash]
+      def line(**options, &block)
+        build_shape(:line, options, &block)
+      end
+
+      # Group shape primitives in a block for readability.
+      #
+      # @yield shape declarations
+      # @return [Array<Hash>]
+      def draw(&block)
+        @type ||= :shape
+        instance_eval(&block) if block
+        @params[:shapes] || []
+      end
+
+      # @param value [Symbol, String] input source for media-like layers
+      # @return [Symbol, Hash]
+      def source(value, **options)
+        source_name = value.to_sym
+        return mapping_source(source_name, **options) if options.any? || MAPPING_SOURCE_KINDS.include?(source_name)
+
+        @params[:source] = source_name
+      end
+
       # @param value [Integer] particle count or similar numeric parameter
       # @return [Integer]
       def count(value)
@@ -61,52 +122,265 @@ module Vizcore
         @params[:font_size] = Integer(value)
       end
 
+      # @param value [Numeric] extra spacing between text glyphs in pixels
+      # @return [Float]
+      def letter_spacing(value)
+        @params[:letter_spacing] = normalize_non_negative_param_number(value, :letter_spacing)
+      end
+
+      # @param value [Symbol, String] text alignment (`left`, `center`, `right`)
+      # @return [Symbol]
+      def align(value)
+        alignment = value.to_sym
+        raise ArgumentError, "unsupported text align: #{value.inspect}" unless %i[left center right].include?(alignment)
+
+        @params[:align] = alignment
+      end
+
+      # @param value [String] text font family
+      # @return [String]
+      def font(value)
+        @params[:font] = value.to_s
+      end
+
+      # @param value [String] text fill color
+      # @return [String]
+      def fill(value)
+        @params[:color] = value.to_s
+      end
+
+      # @param width [Numeric, nil] text stroke width in pixels
+      # @param color [String, nil] text stroke color
+      # @return [Hash]
+      def stroke(value = NO_ARGUMENT, width: nil, color: nil)
+        if @current_shape
+          @current_shape[:stroke] = normalize_non_negative_param_number(value, :stroke) unless value.equal?(NO_ARGUMENT)
+          @current_shape[:stroke_width] = normalize_non_negative_param_number(width, :stroke_width) unless width.nil?
+          @current_shape[:stroke_color] = color.to_s unless color.nil?
+          return @current_shape
+        end
+
+        @params[:stroke_width] = normalize_non_negative_param_number(width, :stroke_width) unless width.nil?
+        @params[:stroke_color] = color.to_s unless color.nil?
+        @params
+      end
+
+      # @param color [String, nil] text shadow color
+      # @param blur [Numeric, nil] text shadow blur in pixels
+      # @return [Hash]
+      def shadow(color: nil, blur: nil)
+        @params[:shadow_color] = color.to_s unless color.nil?
+        @params[:shadow_blur] = normalize_non_negative_param_number(blur, :shadow_blur) unless blur.nil?
+        @params
+      end
+
+      # @param value [Symbol, String] layer compositing mode
+      # @return [Symbol]
+      def blend(value)
+        @params[:blend] = value.to_sym
+      end
+
+      # Store an ordered color palette for this layer.
+      #
+      # @param colors [Array<String, Array<String>>] color values such as "#00ffff"
+      # @raise [ArgumentError] when no non-blank colors are supplied
+      # @return [Array<String>]
+      def palette(*colors)
+        @params[:palette] = normalize_palette(colors)
+      end
+
+      # Apply a named style by merging its params into this layer.
+      #
+      # @param name [Symbol, String] style identifier
+      # @raise [ArgumentError] when the style is unknown
+      # @return [Hash] applied style params
+      def use_style(name)
+        style_name = name.to_sym
+        style_params = @styles.fetch(style_name) { raise ArgumentError, "unknown style: #{style_name}" }
+        @params.merge!(deep_dup(style_params))
+      end
+
+      # Declare numeric metadata for a shader/layer parameter.
+      #
+      # @param name [Symbol, String] parameter name exposed as `u_param_<name>` for shaders
+      # @param default [Numeric, nil] default value stored in layer params
+      # @param range [Range, Array, nil] allowed numeric range
+      # @param min [Numeric, nil] allowed minimum when `range` is not used
+      # @param max [Numeric, nil] allowed maximum when `range` is not used
+      # @param step [Numeric, nil] preferred UI step
+      # @return [Hash]
+      def param(name, default: nil, range: nil, min: nil, max: nil, step: nil)
+        key = normalize_param_name(name)
+        range_min, range_max = normalize_range(range, context: "param")
+        min = range_min if min.nil?
+        max = range_max if max.nil?
+
+        metadata = { name: key }
+        metadata[:default] = normalize_param_number(default, :default) unless default.nil?
+        metadata[:min] = normalize_param_number(min, :min) unless min.nil?
+        metadata[:max] = normalize_param_number(max, :max) unless max.nil?
+        metadata[:step] = normalize_param_number(step, :step) unless step.nil?
+        validate_param_range!(metadata)
+
+        @params[key] = metadata[:default] if metadata.key?(:default)
+        @param_schema[key] = metadata
+      end
+
       # Map analysis source(s) to layer parameter target(s).
       #
-      # @param definition [Hash] mapping pairs (`source` => `target`)
+      # @param definition [Hash, Symbol, String] mapping pairs or a single source
       # @raise [ArgumentError] when the mapping is empty or invalid
       # @return [void]
-      def map(definition)
-        mapping = Hash(definition)
+      def map(definition = nil, **options, &block)
+        definition, options = normalize_shape_mapping(definition, options) if @shape_target_prefix
+
+        if options.key?(:to)
+          transform_options = options.dup
+          to = transform_options.delete(:to)
+          transform_options = evaluate_transform_block(transform_options, &block) if block
+          @mappings << build_mapping(
+            source: normalize_source(definition),
+            target: to,
+            transform: normalize_transform(**transform_options)
+          )
+          return
+        end
+
+        mapping = definition.nil? ? options : Hash(definition)
         raise ArgumentError, "map requires at least one mapping pair" if mapping.empty?
+        raise ArgumentError, "map block syntax supports one mapping pair" if block && mapping.length != 1
 
         mapping.each do |source, target|
-          @mappings << {
-            source: normalize_source(source),
-            target: target.to_sym
-          }
+          target_name, transform = normalize_target(target)
+          transform = normalize_transform(**evaluate_transform_block(transform, &block)) if block
+          @mappings << build_mapping(source: normalize_source(source), target: target_name, transform: transform)
         end
       end
 
+      # High-level mapping DSL for describing audio reactions inside a layer.
+      #
+      # @param source_value [Hash, Symbol, String] analysis source descriptor
+      # @yield Reaction block with `change` and `trigger`
+      # @raise [ArgumentError] when no reaction block is provided
+      # @return [void]
+      def react_to(source_value, &block)
+        raise ArgumentError, "react_to requires a block" unless block
+
+        source_descriptor = normalize_source(source_value)
+        reaction = ReactionBuilder.new(
+          mapping_factory: lambda do |target, transform_options|
+            build_mapping(
+              source: source_descriptor,
+              target: target,
+              transform: normalize_transform(**transform_options)
+            )
+          end
+        )
+        @mappings.concat(reaction.evaluate(&block))
+      end
+
       # @return [Hash] source descriptor for overall amplitude
       def amplitude
-        source(:amplitude)
+        mapping_source(:amplitude)
       end
 
       # @param name [Symbol, String] band key (`sub`, `low`, `mid`, `high`)
       # @return [Hash] source descriptor for a frequency band
       def frequency_band(name)
-        source(:frequency_band, band: name.to_sym)
+        mapping_source(:frequency_band, 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 low/bass frequency band
+      def low
+        frequency_band(:low)
+      end
+
+      # @return [Hash] source descriptor for the low/bass frequency band
+      def bass
+        frequency_band(:low)
+      end
+
+      # @return [Hash] source descriptor for the mid frequency band
+      def mid
+        frequency_band(:mid)
+      end
+
+      # @return [Hash] source descriptor for the high frequency band
+      def high
+        frequency_band(:high)
+      end
+
+      # @return [Hash] source descriptor for the high/treble frequency band
+      def treble
+        frequency_band(:high)
       end
 
       # @return [Hash] source descriptor for FFT spectrum array
       def fft_spectrum
-        source(:fft_spectrum)
+        mapping_source(:fft_spectrum)
+      end
+
+      # @param band [Symbol, String, nil] optional band-specific onset key
+      # @return [Hash] source descriptor for positive audio feature changes
+      def onset(band = nil)
+        options = band.nil? ? {} : { band: band.to_sym }
+        mapping_source(:onset, **options)
+      end
+
+      # @return [Hash] source descriptor for low-band percussive confidence
+      def kick(value = NO_ARGUMENT)
+        return @params[:kick] = value unless value.equal?(NO_ARGUMENT)
+
+        mapping_source(:kick)
+      end
+
+      # @return [Hash] source descriptor for mid-band percussive confidence
+      def snare(value = NO_ARGUMENT)
+        return @params[:snare] = value unless value.equal?(NO_ARGUMENT)
+
+        mapping_source(:snare)
+      end
+
+      # @return [Hash] source descriptor for high-band percussive confidence
+      def hihat(value = NO_ARGUMENT)
+        return @params[:hihat] = value unless value.equal?(NO_ARGUMENT)
+
+        mapping_source(:hihat)
       end
 
       # @return [Hash] source descriptor for beat trigger
       def beat?
-        source(:beat)
+        mapping_source(:beat)
+      end
+
+      # @return [Hash] source descriptor for beat trigger
+      def beat
+        beat?
+      end
+
+      # @return [Hash] source descriptor for beat detector confidence
+      def beat_confidence
+        mapping_source(:beat_confidence)
+      end
+
+      # @return [Hash] source descriptor for beat pulse decay value
+      def beat_pulse
+        mapping_source(:beat_pulse)
       end
 
       # @return [Hash] source descriptor for beat counter
       def beat_count
-        source(:beat_count)
+        mapping_source(:beat_count)
       end
 
       # @return [Hash] source descriptor for estimated BPM
       def bpm
-        source(:bpm)
+        mapping_source(:bpm)
       end
 
       # @return [Hash] serialized layer payload
@@ -118,6 +392,7 @@ module Vizcore
         }
         layer[:shader] = @shader if @shader
         layer[:glsl] = @glsl if @glsl
+        layer[:param_schema] = @param_schema.values.map(&:dup) unless @param_schema.empty?
         layer[:mappings] = @mappings.map { |mapping| mapping.dup } unless @mappings.empty?
         layer
       end
@@ -125,6 +400,11 @@ module Vizcore
       # Stores dynamic one-argument setters into `params`.
       # @api private
       def method_missing(method_name, *args, &block)
+        if @current_shape && block.nil? && args.length == 1
+          @current_shape[method_name.to_sym] = args.first
+          return args.first
+        end
+
         if block.nil? && args.length == 1
           @params[method_name.to_sym] = args.first
           return args.first
@@ -139,6 +419,65 @@ module Vizcore
 
       private
 
+      def build_shape(kind, options, &block)
+        @type ||= :shape
+        shape = normalize_shape(kind, options)
+        @params[:shapes] ||= []
+        shape_index = @params[:shapes].length
+        @params[:shapes] << shape
+
+        with_shape_context(shape, shape_index) do
+          instance_eval(&block) if block
+        end
+
+        shape
+      end
+
+      def normalize_shape(kind, options)
+        shape = { kind: kind.to_sym }
+        options.each do |key, value|
+          shape[key.to_sym] = value
+        end
+        shape
+      end
+
+      def with_shape_context(shape, shape_index)
+        previous_shape = @current_shape
+        previous_prefix = @shape_target_prefix
+        @current_shape = shape
+        @shape_target_prefix = "shapes.#{shape_index}"
+        yield
+      ensure
+        @current_shape = previous_shape
+        @shape_target_prefix = previous_prefix
+      end
+
+      def normalize_shape_mapping(definition, options)
+        if options.key?(:to)
+          prefixed_options = options.dup
+          prefixed_options[:to] = prefixed_shape_target(prefixed_options[:to])
+          return [definition, prefixed_options]
+        end
+
+        mapping = definition.nil? ? options : Hash(definition)
+        prefixed_mapping = mapping.each_with_object({}) do |(source, target), output|
+          output[source] = prefix_shape_target_value(target)
+        end
+        [prefixed_mapping, {}]
+      end
+
+      def prefix_shape_target_value(target)
+        return prefixed_shape_target(target) unless target.is_a?(Hash)
+
+        target.merge(to: prefixed_shape_target(target.fetch(:to)))
+      rescue KeyError
+        target
+      end
+
+      def prefixed_shape_target(target)
+        :"#{@shape_target_prefix}.#{target}"
+      end
+
       def resolved_type
         return @type if @type
         return :shader if @shader || @glsl
@@ -146,17 +485,24 @@ module Vizcore
         :geometry
       end
 
+      def shader_path?(value)
+        return false if value.is_a?(Symbol)
+
+        path = value.to_s
+        %w[.frag .glsl].include?(File.extname(path).downcase) || path.include?("/")
+      end
+
       def normalize_source(source_value)
         case source_value
         when Hash
           kind = source_value[:kind] || source_value["kind"]
           raise ArgumentError, "mapping source hash must contain :kind" unless kind
 
-          source(kind.to_sym, **normalize_source_options(source_value))
+          mapping_source(kind.to_sym, **normalize_source_options(source_value))
         when Symbol
-          source(source_value)
+          mapping_source(source_value)
         when String
-          source(source_value.to_sym)
+          mapping_source(source_value.to_sym)
         else
           raise ArgumentError, "unsupported mapping source: #{source_value.inspect}"
         end
@@ -171,7 +517,130 @@ module Vizcore
         end
       end
 
-      def source(kind, **options)
+      def normalize_target(target)
+        return [target.to_sym, {}] unless target.is_a?(Hash)
+
+        values = target.each_with_object({}) { |(key, value), output| output[key.to_sym] = value }
+        to = values.delete(:to)
+        raise ArgumentError, "mapping target hash must contain :to" unless to
+
+        [to.to_sym, normalize_transform(**values)]
+      end
+
+      def build_mapping(source:, target:, transform: {})
+        output = { source: source, target: target.to_sym }
+        output[:transform] = transform unless transform.empty?
+        output
+      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
+      end
+
+      def evaluate_transform_block(initial_options, &block)
+        MappingTransformBuilder.new(initial_options).evaluate(&block).to_h
+      end
+
+      def normalize_param_name(name)
+        key = name.to_s.strip
+        raise ArgumentError, "param name is required" if key.empty?
+
+        key.to_sym
+      end
+
+      def normalize_palette(colors)
+        values = colors.flatten.map { |color| color.to_s.strip }.reject(&:empty?)
+        raise ArgumentError, "layer #{@name} palette requires at least one color" if values.empty?
+
+        values
+      end
+
+      def normalize_param_number(value, name)
+        Float(value)
+      rescue ArgumentError, TypeError
+        raise ArgumentError, "param #{name} must be numeric"
+      end
+
+      def validate_param_range!(metadata)
+        return unless metadata.key?(:min) && metadata.key?(:max)
+        return if metadata[:min] <= metadata[:max]
+
+        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)
+        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[: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
+      end
+
+      def normalize_range(value, context:)
+        return [nil, nil] if value.nil?
+
+        if value.is_a?(Range)
+          return [value.begin, value.end]
+        end
+
+        if value.is_a?(Array) && value.length == 2
+          return value
+        end
+
+        raise ArgumentError, "#{context} range must be a Range or two-element Array"
+      end
+
+      def normalize_float(value, name)
+        Float(value)
+      rescue ArgumentError, TypeError
+        raise ArgumentError, "mapping #{name} must be numeric"
+      end
+
+      def normalize_non_negative_float(value, name)
+        numeric = normalize_float(value, name)
+        raise ArgumentError, "mapping #{name} must be non-negative" if numeric.negative?
+
+        numeric
+      end
+
+      def normalize_non_negative_param_number(value, name)
+        numeric = Float(value)
+        raise ArgumentError, "#{name} must be non-negative" if numeric.negative?
+
+        numeric
+      rescue ArgumentError, TypeError
+        raise ArgumentError, "#{name} must be numeric"
+      end
+
+      def normalize_curve(value)
+        curve = value.to_sym
+        return curve if %i[linear sqrt square ease_out].include?(curve)
+
+        raise ArgumentError, "unsupported mapping curve: #{value.inspect}"
+      end
+
+      def clamp(value, min, max)
+        [[value, min].max, max].min
+      end
+
+      def mapping_source(kind, **options)
         {
           kind: kind.to_sym,
           **options