vizcore 1.1.0 → 1.2.0

data/lib/vizcore/dsl/midi_map_executor.rb

@@ -19,6 +19,7 @@ module Vizcore
         @midi_maps = normalize_midi_maps(midi_maps)
         @scenes = normalize_scenes(scenes)
         @globals = normalize_globals(globals) unless globals.nil?
+        @cc_state = {}
       end
 
       # @return [Hash] mutable global parameter snapshot
@@ -32,8 +33,11 @@ module Vizcore
         @midi_maps.each_with_object([]) do |mapping, actions|
           next unless mapping_match?(mapping[:trigger], event)
 
+          value = event_value(event, mapping[:trigger])
+          next if value.nil?
+
           context = ActionContext.new(scenes: @scenes, globals: @globals)
-          invoke_action_block(context, mapping[:action], event, mapping[:trigger])
+          invoke_action_block(context, mapping[:action], value)
           actions.concat(context.actions)
         end
       end
@@ -73,6 +77,8 @@ module Vizcore
       end
 
       def mapping_match?(trigger, event)
+        return false unless channel_match?(trigger, event)
+
         if trigger.key?(:note)
           event.type == :note_on && event.data1 == trigger[:note].to_i
         elsif trigger.key?(:cc)
@@ -84,8 +90,13 @@ module Vizcore
         end
       end
 
-      def invoke_action_block(context, action, event, trigger)
-        value = event_value(event, trigger)
+      def channel_match?(trigger, event)
+        return true unless trigger.key?(:channel)
+
+        event.channel.to_i == trigger[:channel].to_i
+      end
+
+      def invoke_action_block(context, action, value)
         if action.arity.zero?
           context.instance_exec(&action)
         else
@@ -94,8 +105,10 @@ module Vizcore
       end
 
       def event_value(event, trigger)
-        if trigger.key?(:note) || trigger.key?(:cc)
+        if trigger.key?(:note)
           event.data2.to_i.clamp(0, 127)
+        elsif trigger.key?(:cc)
+          cc_event_value(event, trigger)
         elsif trigger.key?(:pc)
           event.data1.to_i.clamp(0, 127)
         else
@@ -103,6 +116,78 @@ module Vizcore
         end
       end
 
+      def cc_event_value(event, trigger)
+        raw = event.data2.to_i.clamp(0, 127)
+        state = (@cc_state[state_key(trigger)] ||= {})
+        value = trigger[:relative] ? relative_cc_delta(raw) : raw
+        return nil if pickup_blocked?(raw, state, trigger)
+        return nil if within_deadband?(value, state, trigger)
+
+        value = smooth_value(value, state, trigger)
+        state[:last_raw] = raw unless trigger[:relative]
+        state[:last_value] = value
+        value
+      end
+
+      def relative_cc_delta(raw)
+        return raw if raw.between?(1, 63)
+        return raw - 128 if raw.between?(65, 127)
+
+        0
+      end
+
+      def pickup_blocked?(raw, state, trigger)
+        return false unless trigger[:pickup]
+        return false unless trigger.key?(:cc)
+        return false if state[:pickup_synced]
+
+        return false if trigger[:relative]
+
+        reference = state[:pickup_reference_raw]
+        unless reference
+          state[:pickup_reference_raw] = raw
+          return true
+        end
+
+        tolerance = trigger[:deadband] || 1
+        if (raw - reference).abs <= tolerance
+          state[:pickup_synced] = true
+          state[:pickup_reference_raw] = nil
+          return false
+        end
+
+        true
+      end
+
+      def within_deadband?(value, state, trigger)
+        return false unless trigger.key?(:deadband)
+
+        deadband = Float(trigger[:deadband])
+        if trigger[:relative]
+          value.abs <= deadband
+        elsif state.key?(:last_raw)
+          (value - state[:last_raw].to_f).abs <= deadband
+        else
+          false
+        end
+      rescue ArgumentError, TypeError
+        false
+      end
+
+      def smooth_value(value, state, trigger)
+        return value unless trigger.key?(:smooth)
+        return value unless state.key?(:last_value)
+
+        alpha = Float(trigger[:smooth]).clamp(0.0, 1.0)
+        state[:last_value].to_f + ((value - state[:last_value].to_f) * alpha)
+      rescue ArgumentError, TypeError
+        value
+      end
+
+      def state_key(trigger)
+        [trigger[:channel], trigger[:cc]]
+      end
+
       def symbolize_hash(value)
         Hash(value).each_with_object({}) do |(key, entry), output|
           output[key.to_sym] = entry
@@ -112,16 +197,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
 
       # Runtime DSL context used while executing one `midi_map` action block.
@@ -129,6 +205,7 @@ module Vizcore
       class ActionContext
         # Collected runtime actions emitted by DSL calls.
         attr_reader :actions
+        attr_reader :unknown_scene_names
 
         # @param scenes [Hash]
         # @param globals [Hash]
@@ -136,6 +213,7 @@ module Vizcore
           @scenes = scenes
           @globals = globals
           @actions = []
+          @unknown_scene_names = []
         end
 
         # @param name [Symbol, String]
@@ -143,7 +221,11 @@ module Vizcore
         # @return [void]
         def switch_scene(name, effect: nil)
           scene = @scenes[name.to_sym]
-          return unless scene
+          unless scene
+            unknown = name.to_s
+            @unknown_scene_names << unknown unless @unknown_scene_names.include?(unknown)
+            return
+          end
 
           @actions << {
             type: :switch_scene,
@@ -155,6 +237,22 @@ module Vizcore
           }
         end
 
+        # Advance to the next scene in runtime scene order.
+        #
+        # @param effect [Hash, nil]
+        # @return [void]
+        def next_scene(effect: nil)
+          @actions << { type: :next_scene, effect: deep_dup(effect) }
+        end
+
+        # Move to the previous scene in runtime scene order.
+        #
+        # @param effect [Hash, nil]
+        # @return [void]
+        def previous_scene(effect: nil)
+          @actions << { type: :previous_scene, effect: deep_dup(effect) }
+        end
+
         # @param key [Symbol, String]
         # @param value [Object]
         # @return [void]
@@ -168,19 +266,117 @@ module Vizcore
           }
         end
 
+        # @param control [Symbol, String]
+        # @param value [Boolean, nil] target value; nil defaults to true for direct calls
+        # @param fade [Numeric, nil] optional seconds for transition to `value == true`
+        # @param release [Numeric, nil] optional seconds for transition to `value == false`
+        # @return [void]
+        def live_control(control, value = nil, fade: nil, release: nil, color: nil)
+          state = normalize_live_control_state(value)
+          state[:fade] = normalize_control_transition(fade)
+          state[:release] = normalize_control_transition(release)
+          state[:color] = normalize_control_color(color)
+          state.delete(:fade) if state[:fade].nil?
+          state.delete(:release) if state[:release].nil?
+          state.delete(:color) if state[:color].nil?
+
+          @actions << {
+            type: :live_control,
+            control: control.to_s,
+            **state
+          }
+        end
+
+        # @param value [Boolean, nil]
+        # @return [void]
+        def blackout(value = nil, fade: nil, release: nil, color: nil)
+          live_control(:blackout, value, fade: fade, release: release, color: color)
+        end
+
+        # @param value [Boolean, nil]
+        # @return [void]
+        def freeze(value = nil, fade: nil, release: nil)
+          live_control(:freeze, value, fade: fade, release: release)
+        end
+
         private
 
+        def normalize_live_control_state(value)
+          if value.is_a?(Hash)
+            state = value.transform_keys(&:to_sym)
+            enabled = state.key?(:value) ? state[:value] : true
+            return {
+              value: !!enabled,
+              fade: normalize_control_transition(state[:fade]),
+              release: normalize_control_transition(state[:release]),
+              color: normalize_control_color(state[:color]),
+            }
+          end
+
+          { value: !!(value.nil? || value) }
+        end
+
         def deep_dup(value)
-          case value
-          when Hash
-            value.each_with_object({}) do |(key, entry), output|
-              output[key] = deep_dup(entry)
+          Vizcore::DeepCopy.copy(value)
+        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
-          when Array
-            value.map { |entry| deep_dup(entry) }
-          else
-            value
+            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

data/lib/vizcore/dsl/reaction_builder.rb

@@ -37,6 +37,7 @@ module Vizcore
       # @param options [Hash] mapping transform options
       # @return [void]
       def trigger(target, **options)
+        options = options.merge(as: :trigger) unless options.key?(:as)
         change(target, **options)
       end
     end

data/lib/vizcore/dsl/scene_builder.rb

@@ -2,6 +2,8 @@
 
 require_relative "layer_builder"
 require_relative "layer_group_builder"
+require_relative "style_builder"
+require_relative "../deep_copy"
 
 module Vizcore
   module DSL
@@ -10,11 +12,15 @@ module Vizcore
       # @param name [Symbol, String] scene identifier
       # @param styles [Hash] reusable layer parameter styles
       # @param themes [Hash] reusable scene-wide layer parameter themes
+      # @param mapping_presets [Hash] reusable mapping presets
       # @param layers [Array<Hash>] initial layer definitions
-      def initialize(name:, styles: {}, themes: {}, layers: [])
+      # @param strict [Boolean] true when unknown layer params should fail
+      def initialize(name:, styles: {}, themes: {}, mapping_presets: {}, layers: [], strict: false)
         @name = name.to_sym
         @styles = styles
         @themes = themes
+        @mapping_presets = mapping_presets
+        @strict = !!strict
         @theme_name = nil
         @theme_params = {}
         @layers = layers.map { |layer| deep_dup(layer) }
@@ -35,18 +41,83 @@ module Vizcore
       # @yield Layer definition block
       # @return [void]
       def layer(name, &block)
-        builder = LayerBuilder.new(name: name, styles: @styles, defaults: @theme_params)
+        builder = LayerBuilder.new(name: name, styles: @styles, mapping_presets: @mapping_presets, defaults: @theme_params, strict: @strict)
         builder.evaluate(&block)
         @layers << builder.to_h
       end
 
+      # Set defaults applied to every layer in this scene.
+      #
+      # @param params [Hash] layer params
+      # @yield optional defaults block using style-like setters
+      # @return [Hash]
+      def scene_defaults(**params, &block)
+        defaults = params.each_with_object({}) { |(key, value), output| output[key.to_sym] = value }
+        if block
+          block_defaults = StyleBuilder.new(name: :scene_defaults, kind: "scene_defaults").evaluate(&block).to_h[:params]
+          defaults.merge!(block_defaults)
+        end
+        raise ArgumentError, "scene_defaults requires at least one parameter" if defaults.empty?
+
+        @theme_params = deep_dup(@theme_params).merge(defaults)
+        @layers = @layers.map { |layer| apply_theme_defaults(layer, defaults) }
+        deep_dup(@theme_params)
+      end
+
+      # Remove an inherited or previously declared layer by name.
+      #
+      # @param name [Symbol, String]
+      # @return [Hash] removed layer definition
+      def remove_layer(name)
+        index = layer_index!(name)
+        @layers.delete_at(index)
+      end
+
+      # Replace an inherited or previously declared layer while preserving order.
+      #
+      # @param name [Symbol, String]
+      # @yield Layer definition block
+      # @return [Hash] replacement layer definition
+      def replace_layer(name, &block)
+        index = layer_index!(name)
+        builder = LayerBuilder.new(
+          name: name,
+          styles: @styles,
+          mapping_presets: @mapping_presets,
+          defaults: @theme_params,
+          strict: @strict
+        )
+        builder.evaluate(&block)
+        @layers[index] = builder.to_h
+      end
+
+      # Override params on an existing layer without changing its type/shader.
+      #
+      # @param name [Symbol, String]
+      # @param params [Hash]
+      # @yield optional style-like param block
+      # @return [Hash] updated layer definition
+      def override_layer(name, **params, &block)
+        index = layer_index!(name)
+        overrides = params.each_with_object({}) { |(key, value), output| output[key.to_sym] = value }
+        if block
+          block_overrides = StyleBuilder.new(name: name, kind: "override_layer").evaluate(&block).to_h[:params]
+          overrides.merge!(block_overrides)
+        end
+        raise ArgumentError, "override_layer #{name} requires at least one parameter" if overrides.empty?
+
+        layer = deep_dup(@layers[index])
+        layer[:params] = Hash(layer[:params] || {}).merge(overrides)
+        @layers[index] = layer
+      end
+
       # Define a related group of layers with shared params.
       #
       # @param name [Symbol, String] group identifier
       # @yield Layer group definition block
       # @return [void]
       def group(name, &block)
-        builder = LayerGroupBuilder.new(name: name, styles: @styles, defaults: @theme_params)
+        builder = LayerGroupBuilder.new(name: name, styles: @styles, mapping_presets: @mapping_presets, defaults: @theme_params, strict: @strict)
         builder.evaluate(&block)
         @layers.concat(builder.to_a)
       end
@@ -83,17 +154,16 @@ module Vizcore
         themed_layer
       end
 
+      def layer_index!(name)
+        normalized = name.to_sym
+        index = @layers.index { |layer| layer[:name]&.to_sym == normalized }
+        raise ArgumentError, "unknown layer: #{normalized}" unless index
+
+        index
+      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

data/lib/vizcore/dsl/shader_source_resolver.rb

@@ -116,16 +116,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

data/lib/vizcore/dsl/style_builder.rb

@@ -1,9 +1,12 @@
 # frozen_string_literal: true
+require_relative "color_helpers"
 
 module Vizcore
   module DSL
     # Collects reusable layer parameter presets for the `style` DSL.
     class StyleBuilder
+      include ColorHelpers
+
       # @param name [Symbol, String] style identifier
       # @param kind [String] user-facing DSL kind for error messages
       def initialize(name:, kind: "style")

data/lib/vizcore/dsl/timeline_builder.rb

@@ -8,9 +8,11 @@ module Vizcore
 
       Point = Struct.new(:value, :unit, keyword_init: true)
 
-      def initialize(beats_per_bar: DEFAULT_BEATS_PER_BAR)
+      # @param bpm [Numeric, nil] fixed BPM for mixed-unit timeline conversion
+      def initialize(beats_per_bar: DEFAULT_BEATS_PER_BAR, bpm: nil)
         @beats_per_bar = positive_integer(beats_per_bar, "beats_per_bar")
         @entries = []
+        @bpm = positive_float(bpm, "timeline bpm") unless bpm.nil?
       end
 
       # Evaluate a timeline block.
@@ -27,14 +29,16 @@ module Vizcore
       #
       # @param position [Numeric, Point] seconds by default, or a value from `seconds`, `beats`, or `bars`
       # @param scene [Symbol, String] scene to activate at the position
+      # @param cue [Symbol, String, nil] optional cue identifier for marker metadata
       # @return [Hash]
-      def at(position, scene:)
+      def at(position, scene:, cue: nil)
         point = normalize_position(position)
         entry = {
           at: point.value,
           unit: point.unit,
           scene: scene.to_sym
         }
+        entry[:cue] = cue.to_sym if cue
         @entries << entry
         entry
       end
@@ -66,12 +70,13 @@ module Vizcore
 
       # @return [Array<Hash>] generated scene transitions
       def transitions
+        return [] if @entries.length < 2
+
         @entries.each_cons(2).map do |from_entry, to_entry|
-          delta = to_entry.fetch(:at) - from_entry.fetch(:at)
           {
             from: from_entry.fetch(:scene),
             to: to_entry.fetch(:scene),
-            trigger: trigger_for(delta, from_entry.fetch(:unit))
+            trigger: trigger_for(from_entry, to_entry)
           }
         end
       end
@@ -84,8 +89,15 @@ module Vizcore
         seconds(position)
       end
 
-      def trigger_for(delta, unit)
-        case unit
+      def trigger_for(from_entry, to_entry)
+        return trigger_for_same_unit(from_entry, to_entry) unless mixed_units?(from_entry.fetch(:unit), to_entry.fetch(:unit))
+
+        trigger_for_mixed_units(from_entry, to_entry)
+      end
+
+      def trigger_for_same_unit(from_entry, to_entry)
+        delta = to_entry.fetch(:at) - from_entry.fetch(:at)
+        case from_entry.fetch(:unit)
         when :seconds
           proc { seconds >= delta }
         when :beats
@@ -95,12 +107,56 @@ module Vizcore
         end
       end
 
+      def trigger_for_mixed_units(from_entry, to_entry)
+        fixed_bpm = @bpm
+
+        if fixed_bpm
+          from_position = marker_position_seconds(from_entry, fixed_bpm: fixed_bpm)
+          to_position = marker_position_seconds(to_entry, fixed_bpm: fixed_bpm)
+          if from_position && to_position
+            return proc { seconds >= (to_position - from_position) }
+          end
+        end
+
+        convert_position = lambda do |entry, bpm|
+          value = entry.fetch(:at)
+          case entry.fetch(:unit)
+          when :seconds
+            value
+          when :beats
+            return nil unless bpm.to_f.positive?
+
+            value * 60.0 / Float(bpm)
+          else
+            nil
+          end
+        end
+
+        proc do
+          used_bpm = fixed_bpm || bpm
+          from_position = convert_position.call(from_entry, used_bpm)
+          to_position = convert_position.call(to_entry, used_bpm)
+          return false unless from_position && to_position
+
+          seconds >= (to_position - from_position)
+        end
+      end
+
       def validate_entries!
         return if @entries.length < 2
 
-        unit = @entries.first.fetch(:unit)
         @entries.each_cons(2) do |from_entry, to_entry|
-          raise ArgumentError, "timeline entries must use the same unit" unless to_entry.fetch(:unit) == unit
+          if mixed_units?(from_entry.fetch(:unit), to_entry.fetch(:unit))
+            if @bpm
+              from_position = marker_position_seconds(from_entry, fixed_bpm: @bpm)
+              to_position = marker_position_seconds(to_entry, fixed_bpm: @bpm)
+              raise ArgumentError, "timeline entries must increase when converted to seconds" if to_position.nil? || from_position.nil? || to_position <= from_position
+            end
+
+            next
+          end
+
+          raise ArgumentError, "timeline entries must use the same unit" unless to_entry.fetch(:unit) == from_entry.fetch(:unit)
 
           from_position = from_entry.fetch(:at)
           to_position = to_entry.fetch(:at)
@@ -108,6 +164,24 @@ module Vizcore
         end
       end
 
+      def mixed_units?(left_unit, right_unit)
+        left_unit != right_unit
+      end
+
+      def marker_position_seconds(entry, fixed_bpm:)
+        value = entry.fetch(:at)
+        case entry.fetch(:unit)
+        when :seconds
+          value
+        when :beats
+          return nil unless fixed_bpm.to_f.positive?
+
+          value * 60.0 / Float(fixed_bpm)
+        else
+          nil
+        end
+      end
+
       def non_negative_float(value, name)
         numeric = parse_float(value, name)
         raise ArgumentError, "#{name} must be non-negative" if numeric.negative?
@@ -133,6 +207,15 @@ module Vizcore
       rescue ArgumentError, TypeError
         raise ArgumentError, "#{name} must be an integer"
       end
+
+      def positive_float(value, name)
+        numeric = Float(value)
+        raise ArgumentError, "#{name} must be positive" unless numeric.positive?
+
+        numeric
+      rescue ArgumentError, TypeError
+        raise ArgumentError, "#{name} must be numeric"
+      end
     end
   end
 end