vizcore 1.1.0 → 1.2.0

data/lib/vizcore/control_preset.rb

@@ -50,13 +50,42 @@ module Vizcore
       input = value.is_a?(Hash) ? value : {}
       visual_settings = hash_value(input, "visual_settings", "visualSettings", "settings")
       midi_learn_bindings = hash_value(input, "midi_learn_bindings", "midiLearnBindings", "midi")
+      scene_overrides = hash_value(input, "scene_overrides", "sceneOverrides")
 
       {}.tap do |payload|
         payload["visual_settings"] = visual_settings if visual_settings
         payload["midi_learn_bindings"] = midi_learn_bindings if midi_learn_bindings
+        normalized_scene_overrides = normalize_scene_overrides(scene_overrides)
+        payload["scene_overrides"] = normalized_scene_overrides if normalized_scene_overrides
       end
     end
 
+    def normalize_scene_overrides(value)
+      return nil unless value
+      raw_overrides = value.is_a?(Hash) ? value : {}
+      normalized = {}
+
+      raw_overrides.each do |raw_scene, raw_override|
+        scene_name = raw_scene.to_s.strip
+        next if scene_name.empty?
+
+        scene_override = normalize_scene_override(raw_override)
+        next if scene_override.empty?
+
+        normalized[scene_name] = scene_override
+      end
+
+      normalized.empty? ? nil : normalized
+    end
+
+    def normalize_scene_override(value)
+      input = value.is_a?(Hash) ? value : {}
+      {
+        "visual_settings" => hash_value(input, "visual_settings", "visualSettings"),
+        "midi_learn_bindings" => hash_value(input, "midi_learn_bindings", "midiLearnBindings", "midi")
+      }.select { |_, entry| entry }
+    end
+
     def hash_value(input, *keys)
       keys.each do |key|
         value = input[key] || input[key.to_sym]

data/lib/vizcore/deep_copy.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Vizcore
+  # Small recursive copier for plain payload hashes/arrays passed between DSL, server, and renderer.
+  module DeepCopy
+    module_function
+
+    # @param value [Object]
+    # @return [Object]
+    def copy(value)
+      case value
+      when Hash
+        value.each_with_object({}) { |(key, entry), output| output[key] = copy(entry) }
+      when Array
+        value.map { |entry| copy(entry) }
+      else
+        value
+      end
+    end
+  end
+end

data/lib/vizcore/dsl/color_helpers.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+module Vizcore
+  module DSL
+    # Shared color helper methods for Ruby DSL builders.
+    module ColorHelpers
+      def hsl(hue, saturation, lightness)
+        rgb = hsl_to_rgb(Float(hue), Float(saturation), Float(lightness))
+        format("#%02x%02x%02x", *rgb)
+      rescue ArgumentError, TypeError
+        raise ArgumentError, "hsl requires numeric hue, saturation, and lightness"
+      end
+
+      def hsv(hue, saturation, value)
+        rgb = hsv_to_rgb(Float(hue), Float(saturation), Float(value))
+        format("#%02x%02x%02x", *rgb)
+      rescue ArgumentError, TypeError
+        raise ArgumentError, "hsv requires numeric hue, saturation, and value"
+      end
+
+      # Build a reusable gradient descriptor for layer color fields.
+      #
+      # @param type [Symbol, String] :linear, :radial, or a supported gradient kind
+      # @param colors [Array<String>] at least two hex-like color values
+      # @param stops [Array<Numeric>, nil] optional stop points in 0.0..1.0
+      # @param position [Numeric, nil] optional fixed position in 0.0..1.0
+      # @return [Hash]
+      def gradient(type: :linear, colors:, stops: nil, position: nil)
+        gradient_type = normalize_gradient_type(type)
+        normalized_colors = normalize_colors_for_gradient(colors)
+        raise ArgumentError, "gradient requires at least two colors" if normalized_colors.length < 2
+
+        stops = normalize_gradient_stops(stops, normalized_colors.length)
+
+        descriptor = {
+          type: gradient_type,
+          colors: normalized_colors
+        }
+        descriptor[:stops] = stops if stops
+        descriptor[:position] = normalize_gradient_position(position) unless position.nil?
+        { gradient: descriptor }
+      rescue ArgumentError, TypeError
+        raise
+      rescue StandardError
+        raise ArgumentError, "gradient requires numeric or parseable color values"
+      end
+
+      private
+
+      def hsl_to_rgb(hue, saturation, lightness)
+        hue = hue % 360.0
+        saturation = normalize_percent_value(saturation)
+        lightness = normalize_percent_value(lightness)
+
+        return [0, 0, 0] if saturation.zero?
+
+        q = lightness < 0.5 ? lightness * (1.0 + saturation) : lightness + saturation - (lightness * saturation)
+        p = 2.0 * lightness - q
+        h = hue / 360.0
+
+        [
+          hue_channel_to_rgb(h + 1.0 / 3.0, p, q),
+          hue_channel_to_rgb(h, p, q),
+          hue_channel_to_rgb(h - 1.0 / 3.0, p, q)
+        ]
+      end
+
+      def hue_channel_to_rgb(value, p, q)
+        value += 1.0 while value < 0.0
+        value -= 1.0 while value > 1.0
+
+        channel =
+          if value < 1.0 / 6.0
+            p + (q - p) * 6.0 * value
+          elsif value < 1.0 / 2.0
+            q
+          elsif value < 2.0 / 3.0
+            p + (q - p) * (2.0 / 3.0 - value) * 6.0
+          else
+            p
+          end
+
+        (channel * 255.0).round.clamp(0, 255)
+      end
+
+      def hsv_to_rgb(hue, saturation, value)
+        hue = hue % 360.0
+        saturation = normalize_percent_value(saturation)
+        value = normalize_percent_value(value)
+        return [0, 0, 0] if saturation.zero?
+
+        sector = hue / 60.0
+        i = sector.floor.to_i
+        f = sector - i
+        p = value * (1.0 - saturation)
+        q = value * (1.0 - f * saturation)
+        t = value * (1.0 - (1.0 - f) * saturation)
+
+        [
+          [value, t, p],
+          [q, value, p],
+          [p, value, t],
+          [p, q, value],
+          [t, p, value],
+          [value, p, q]
+        ][i % 6].map { |channel| (channel * 255.0).round.clamp(0, 255) }
+      end
+
+      def normalize_percent_value(value)
+        normalized = Float(value)
+        return normalized / 100.0 if normalized > 1.0
+
+        normalized.clamp(0.0, 1.0)
+      end
+
+      def normalize_gradient_type(value)
+        symbol = value.to_s.strip.downcase
+        raise ArgumentError, "gradient type must be linear or radial" if symbol.empty?
+
+        case symbol
+        when "linear", "radial"
+          symbol
+        else
+          raise ArgumentError, "unsupported gradient type: #{value}"
+        end
+      end
+
+      def normalize_colors_for_gradient(colors)
+        values = Array(colors).flatten.map { |color| color.to_s.strip }.reject(&:empty?)
+        raise ArgumentError, "gradient requires at least two colors" if values.empty?
+
+        values.each do |value|
+          next if value.match?(/^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/)
+          raise ArgumentError, "gradient colors must be hex strings"
+        end
+
+        values
+      end
+
+      def normalize_gradient_stops(stops, color_count)
+        return nil if stops.nil?
+
+        values = Array(stops).map { |value| Float(value) }
+        raise ArgumentError, "gradient stops must match color count" if values.length != color_count
+
+        values
+      end
+
+      def normalize_gradient_position(value)
+        value = Float(value)
+        value.clamp(0.0, 1.0)
+      end
+    end
+  end
+end

data/lib/vizcore/dsl/engine.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "pathname"
+require_relative "../deep_copy"
 require_relative "file_watcher"
 require_relative "scene_builder"
 require_relative "style_builder"
@@ -76,12 +77,15 @@ module Vizcore
         @midi_mappings = []
         @key_mappings = []
         @global_params = {}
+        @mapping_presets = {}
         @analysis_settings = {}
         @section_tail = nil
         @timelines = []
         @styles = {}
         @themes = {}
         @scene_registry = {}
+        @strict = false
+        @seed = nil
       end
 
       # Evaluate DSL methods on this engine instance.
@@ -124,6 +128,17 @@ module Vizcore
         @themes[theme_definition[:name]] = deep_dup(theme_definition[:params])
       end
 
+      # Register reusable mapping behavior for layer-level targets.
+      #
+      # @param name [Symbol, String] mapping preset identifier
+      # @yield Mapping preset block
+      # @return [void]
+      def mapping(name, &block)
+        builder = MappingPresetBuilder.new(name: name, strict: @strict)
+        preset_definition = builder.evaluate(&block).to_h
+        @mapping_presets[preset_definition[:name]] = deep_dup(preset_definition[:mappings])
+      end
+
       # Register a MIDI input definition.
       #
       # @param name [Symbol, String] input name
@@ -133,6 +148,23 @@ module Vizcore
         @midi_inputs << { name: name.to_sym, options: symbolize_keys(options) }
       end
 
+      # Enable strict DSL validation while the file is evaluated.
+      #
+      # @return [Boolean]
+      def strict!
+        @strict = true
+      end
+
+      # Set a deterministic Ruby random seed for offline rendering.
+      #
+      # @param value [Integer]
+      # @return [Integer]
+      def seed(value)
+        @seed = Integer(value)
+      rescue ArgumentError, TypeError
+        raise ArgumentError, "seed must be an integer"
+      end
+
       # Configure analysis-level audio feature normalization.
       #
       # @param mode [Symbol, String] `:off` or `:adaptive`
@@ -143,6 +175,15 @@ module Vizcore
         @analysis_settings[:audio_normalize] = settings
       end
 
+      # Configure analysis feature extraction behavior.
+      #
+      # @param options [Hash] optional onset/FFT/silence/peak-hold settings
+      # @return [Hash] normalized analysis settings
+      def audio_analysis(**options)
+        settings = normalize_audio_analysis(options)
+        @analysis_settings.merge!(settings)
+      end
+
       # Set a fixed BPM value for analysis output.
       #
       # @param value [Numeric]
@@ -177,7 +218,7 @@ module Vizcore
       # @yield Scene definition block
       # @return [void]
       def scene(name, extends: nil, &block)
-        builder = SceneBuilder.new(name: name, styles: @styles, themes: @themes, layers: inherited_layers(extends))
+        builder = SceneBuilder.new(name: name, styles: @styles, themes: @themes, mapping_presets: @mapping_presets, layers: inherited_layers(extends), strict: @strict)
         builder.evaluate(&block)
         scene_definition = builder.to_h
         @scenes << scene_definition
@@ -190,15 +231,30 @@ module Vizcore
       # @param name [Symbol, String] scene/section identifier
       # @param bars [Integer] section duration in bars
       # @param beats_per_bar [Integer] meter used to convert bars into beats
+      # @param loop [Boolean] whether the section should loop to itself
+      # @param hold [Numeric] optional additional beats to wait before transitioning
+      # @param outro [Boolean] whether to skip auto-transitioning to the next section
       # @yield Scene definition block
       # @return [void]
-      def section(name, bars:, beats_per_bar: 4, &block)
+      def section(name, bars:, beats_per_bar: 4, loop: false, hold: 0, outro: false, &block)
         section_name = name.to_sym
         section_beats = positive_integer(bars, "section bars") * positive_integer(beats_per_bar, "beats_per_bar")
+        normalized_hold = non_negative_float(hold, "section hold")
+        is_loop = !!loop
+        is_outro = !!outro
+        if is_loop && is_outro
+          raise ArgumentError, "section cannot be both loop and outro"
+        end
 
         scene(section_name, &block)
         add_section_transition(to: section_name) if @section_tail
-        @section_tail = { name: section_name, beats: section_beats }
+        @section_tail = {
+          name: section_name,
+          beats: section_beats,
+          hold: normalized_hold,
+          loop: is_loop,
+          outro: is_outro
+        }
       end
 
       # Define ordered scene markers and derive transitions between them.
@@ -209,7 +265,7 @@ module Vizcore
       def timeline(beats_per_bar: TimelineBuilder::DEFAULT_BEATS_PER_BAR, &block)
         raise ArgumentError, "timeline requires a block" unless block
 
-        builder = TimelineBuilder.new(beats_per_bar: beats_per_bar).evaluate(&block)
+        builder = TimelineBuilder.new(beats_per_bar: beats_per_bar, bpm: @analysis_settings[:bpm]).evaluate(&block)
         entries = builder.to_h
         @timelines << entries unless entries.empty?
         @transitions.concat(builder.transitions)
@@ -236,15 +292,26 @@ module Vizcore
       # @param note [Integer, nil] note number trigger
       # @param cc [Integer, nil] control-change trigger
       # @param pc [Integer, nil] program-change trigger
+      # @param channel [Integer, nil] optional MIDI channel condition (1..16; 0 aliases channel 1)
+      # @param relative [Boolean] true when CC values should be treated as relative encoder deltas
+      # @param deadband [Numeric, nil] minimum CC value change required to emit an action
+      # @param smooth [Numeric, Boolean, nil] optional CC smoothing alpha
+      # @param pickup [Boolean, nil] when true, waits for CC to reach local pickup point before emitting updates
       # @yield Action block executed by midi runtime
       # @raise [ArgumentError] when no trigger is supplied
       # @return [void]
-      def midi_map(note: nil, cc: nil, pc: nil, &block)
+      def midi_map(note: nil, cc: nil, pc: nil, channel: nil, relative: false, deadband: nil, smooth: nil, pickup: nil, allow_multiple: false, &block)
         trigger = {}
         trigger[:note] = Integer(note) unless note.nil?
         trigger[:cc] = Integer(cc) unless cc.nil?
         trigger[:pc] = Integer(pc) unless pc.nil?
         raise ArgumentError, "midi_map requires note, cc or pc" if trigger.empty?
+        trigger[:channel] = normalize_midi_channel(channel) unless channel.nil?
+        trigger[:relative] = true if relative && trigger.key?(:cc)
+        trigger[:deadband] = non_negative_float(deadband, "midi deadband") unless deadband.nil?
+        trigger[:smooth] = normalize_midi_smooth(smooth) unless smooth.nil? || smooth == false
+        trigger[:pickup] = pickup if trigger.key?(:cc) && trigger[:cc].between?(0, 127) && !!pickup
+        trigger[:allow_multiple] = !!allow_multiple
 
         @midi_mappings << {
           trigger: trigger,
@@ -282,6 +349,7 @@ module Vizcore
 
       # @return [Hash] deep-copied definition payload for renderer/runtime.
       def result
+        append_pending_section_transition
         definition = {
           audio: @audio_inputs.map { |item| deep_dup(item) },
           midi: @midi_inputs.map { |item| deep_dup(item) },
@@ -289,11 +357,14 @@ module Vizcore
           transitions: @transitions.map { |transition| deep_dup(transition) },
           midi_maps: @midi_mappings.map { |mapping| deep_dup(mapping) },
           key_mappings: @key_mappings.map { |mapping| deep_dup(mapping) },
+          mapping_presets: @mapping_presets.map { |name, mappings| { name: name, mappings: deep_dup(mappings) } },
           globals: deep_dup(@global_params),
           analysis: deep_dup(@analysis_settings),
           styles: @styles.map { |name, params| { name: name, params: deep_dup(params) } },
           themes: @themes.map { |name, params| { name: name, params: deep_dup(params) } }
         }
+        definition[:strict] = true if @strict
+        definition[:seed] = @seed unless @seed.nil?
         definition[:timelines] = @timelines.map { |timeline| deep_dup(timeline) } unless @timelines.empty?
         definition
       end
@@ -314,6 +385,17 @@ module Vizcore
         settings[:window] = positive_float(options[:window], "audio_normalize window") if options.key?(:window)
         settings[:target] = unit_float(options[:target], "audio_normalize target") if options.key?(:target)
         settings[:floor] = unit_float(options[:floor], "audio_normalize floor") if options.key?(:floor)
+        settings[:per_band] = !!options[:per_band] if options.key?(:per_band)
+        settings
+      end
+
+      def normalize_audio_analysis(options)
+        settings = {}
+        settings[:onset_sensitivity] = positive_float(options[:onset_sensitivity], "onset_sensitivity") if options.key?(:onset_sensitivity)
+        settings[:fft_bins] = ranged_integer(options[:fft_bins], "fft_bins", 8, 128) if options.key?(:fft_bins)
+        peak_hold = options.key?(:peak_hold) ? options[:peak_hold] : options[:peak_hold_frames]
+        settings[:peak_hold_frames] = ranged_integer(peak_hold, "peak_hold", 0, 10_000) unless peak_hold.nil?
+        settings[:silence_reset_frames] = ranged_integer(options[:silence_reset_frames], "silence_reset_frames", 1, 10_000) if options.key?(:silence_reset_frames)
         settings
       end
 
@@ -324,6 +406,39 @@ module Vizcore
         numeric
       end
 
+      def ranged_integer(value, name, min, max)
+        numeric = Integer(value)
+        raise ArgumentError, "#{name} must be between #{min} and #{max}" unless numeric.between?(min, max)
+
+        numeric
+      end
+
+      def normalize_midi_channel(value)
+        channel = Integer(value)
+        return 0 if channel.zero?
+        return channel - 1 if channel.between?(1, 16)
+
+        raise ArgumentError, "midi channel must be between 1 and 16"
+      end
+
+      def non_negative_float(value, name)
+        numeric = Float(value)
+        raise ArgumentError, "#{name} must be non-negative" if numeric.negative?
+
+        numeric
+      end
+
+      def normalize_midi_smooth(value)
+        return 0.25 if value == true
+
+        numeric = Float(value)
+        raise ArgumentError, "midi smooth must be between 0.0 and 1.0" unless numeric.between?(0.0, 1.0)
+
+        numeric
+      rescue ArgumentError, TypeError
+        raise ArgumentError, "midi smooth must be true or between 0.0 and 1.0"
+      end
+
       def positive_float(value, name)
         numeric = Float(value)
         raise ArgumentError, "#{name} must be positive" unless numeric.positive?
@@ -352,11 +467,29 @@ module Vizcore
       def add_section_transition(to:)
         from = @section_tail.fetch(:name)
         beats = @section_tail.fetch(:beats)
+        hold = @section_tail.fetch(:hold, 0.0)
+        return if @section_tail.fetch(:loop, false)
+        return if @section_tail.fetch(:outro, false)
+
         @transitions << {
           from: from,
           to: to,
-          trigger: proc { beat_count >= beats }
+          trigger: proc { beat_count >= (beats + hold) }
+        }
+      end
+
+      def append_pending_section_transition
+        return unless @section_tail && @section_tail.fetch(:loop, false)
+
+        from = @section_tail.fetch(:name)
+        beats = @section_tail.fetch(:beats, 0)
+        hold = @section_tail.fetch(:hold, 0.0)
+        @transitions << {
+          from: from,
+          to: from,
+          trigger: proc { beat_count >= (beats + hold) }
         }
+        @section_tail = @section_tail.merge(loop: false)
       end
 
       def inherited_layers(scene_name)
@@ -370,16 +503,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
 
       # Builder object for `transition` block internals.
@@ -451,36 +575,50 @@ module Vizcore
         #
         # @param name [Symbol, String]
         # @return [void]
-        def switch_scene(name)
+        def switch_scene(name, effect: nil)
           scene_name = name.to_s.strip
           raise ArgumentError, "switch_scene scene must not be empty" if scene_name.empty?
 
-          assign_action(type: :switch_scene, scene: scene_name)
+          action = { type: :switch_scene, scene: scene_name }
+          action[:effect] = effect unless effect.nil?
+          assign_action(action)
         end
 
         # Toggle browser blackout output.
         #
         # @return [void]
-        def blackout
-          live_control(:blackout)
+        def blackout(value = nil, fade: nil, release: nil, color: nil)
+          live_control(:blackout, value, fade: fade, release: release, color: color)
         end
 
         # Toggle browser freeze output.
         #
         # @return [void]
-        def freeze
-          live_control(:freeze)
+        def freeze(value = nil, fade: nil, release: nil)
+          live_control(:freeze, value, fade: fade, release: release)
         end
 
         # Toggle a browser live control.
         #
         # @param control [Symbol, String]
+        # @param value [Object, nil] target value; nil means UI-side toggle for keyboard/live mapping
         # @return [void]
-        def live_control(control)
+        def live_control(control, value = nil, fade: nil, release: nil, color: nil)
           normalized = control.to_s.strip.downcase.to_sym
           raise ArgumentError, "unsupported live control: #{control}" unless %i[blackout freeze].include?(normalized)
 
           assign_action(type: :live_control, control: normalized)
+
+          # Preserve explicit value and transition timings when provided by DSL authors.
+          # `nil` is kept for UI-side toggles to avoid changing existing keyboard ergonomics.
+          action = @action
+          action[:value] = value unless value.nil?
+          action[:fade] = normalize_control_transition(fade)
+          action[:release] = normalize_control_transition(release)
+          action[:color] = normalize_control_color(color) unless color.nil?
+          action.delete(:fade) if action[:fade].nil?
+          action.delete(:release) if action[:release].nil?
+          action.delete(:color) if action[:color].nil?
         end
 
         # @return [Hash] serialized key action
@@ -495,6 +633,64 @@ module Vizcore
 
           @action = action
         end
+
+        def normalize_control_transition(value)
+          return nil if value.nil?
+
+          numeric = Float(value)
+          return nil if numeric.negative? || !numeric.finite?
+
+          numeric
+        rescue ArgumentError, TypeError
+          nil
+        end
+
+        def normalize_control_color(value)
+          return nil if value.nil?
+
+          if value.is_a?(Array)
+            return nil unless (3..4).cover?(value.length)
+
+            channels = Array(value).map { |entry| Float(entry, exception: false) }
+            return nil if channels.include?(nil)
+
+            rgb = channels.take(3)
+            alpha = channels[3]
+            normalized_rgb = if rgb.all? { |channel| channel.between?(0.0, 1.0) }
+              rgb
+            else
+              rgb.map { |channel| channel / 255.0 }
+            end
+            normalized = normalized_rgb.map { |channel| [0.0, [1.0, channel].min].max }
+            return alpha.nil? ? normalized : normalized + [normalize_control_alpha(alpha)]
+          end
+
+          raw = value.to_s.strip
+          match = raw.match(/^#([0-9a-fA-F]{3}|[0-9a-fA-F]{4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/)
+          return nil unless match
+
+          raw_hex = match[1]
+          hex = raw_hex.length == 3 || raw_hex.length == 4 ? raw_hex.chars.map { |char| "#{char}#{char}" }.join("") : raw_hex
+
+          [
+            Integer("0x#{hex[0, 2]}", 16),
+            Integer("0x#{hex[2, 2]}", 16),
+            Integer("0x#{hex[4, 2]}", 16),
+            Integer("0x#{hex[6, 2]}", 16)
+          ].take(raw_hex.length > 4 ? 4 : 3).map { |channel| [0.0, [1.0, channel / 255.0].min].max }
+        rescue ArgumentError, TypeError
+          nil
+        end
+
+        def normalize_control_alpha(value)
+          return nil if value.nil?
+
+          alpha = Float(value, exception: false)
+          return nil if alpha.nil?
+          return [0.0, [1.0, alpha].min].max if alpha.between?(0.0, 1.0)
+
+          [0.0, [1.0, alpha / 255.0].min].max
+        end
       end
     end
   end