vizcore 0.1.0 → 1.0.0

data/lib/vizcore/dsl/layer_group_builder.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require_relative "layer_builder"
+
+module Vizcore
+  module DSL
+    # Collects related layers and applies shared layer parameters.
+    class LayerGroupBuilder
+      # @param name [Symbol, String] group identifier stored on nested layer params
+      # @param styles [Hash] reusable layer parameter styles
+      # @param defaults [Hash] scene defaults already applied before group params
+      def initialize(name:, styles: {}, defaults: {})
+        @name = name.to_sym
+        @styles = styles
+        @params = deep_dup(defaults)
+        @layers = []
+      end
+
+      # Evaluate a group block.
+      #
+      # @yield Layer group DSL methods
+      # @return [Vizcore::DSL::LayerGroupBuilder]
+      def evaluate(&block)
+        instance_eval(&block) if block
+        self
+      end
+
+      # Define one layer in this group.
+      #
+      # @param name [Symbol, String] layer identifier
+      # @yield Layer definition block
+      # @return [void]
+      def layer(name, &block)
+        builder = LayerBuilder.new(name: name, styles: @styles, defaults: layer_defaults)
+        builder.evaluate(&block)
+        @layers << builder.to_h
+      end
+
+      # @param value [Symbol, String] layer compositing mode shared by nested layers
+      # @return [Symbol]
+      def blend(value)
+        @params[:blend] = value.to_sym
+      end
+
+      # Store an ordered color palette shared by nested layers.
+      #
+      # @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
+
+      # Merge a named style into this group's shared params.
+      #
+      # @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
+
+      # @return [Array<Hash>] serialized nested layers
+      def to_a
+        @layers.map { |layer| deep_dup(layer) }
+      end
+
+      # Stores dynamic one-argument setters into shared group params.
+      # @api private
+      def method_missing(method_name, *args, &block)
+        if block.nil? && args.length == 1
+          @params[method_name.to_sym] = args.first
+          return args.first
+        end
+
+        super
+      end
+
+      def respond_to_missing?(method_name, include_private = false)
+        @params.key?(method_name.to_sym) || super
+      end
+
+      private
+
+      def layer_defaults
+        deep_dup(@params).merge(group: @name)
+      end
+
+      def normalize_palette(colors)
+        values = colors.flatten.map { |color| color.to_s.strip }.reject(&:empty?)
+        raise ArgumentError, "group #{@name} palette requires at least one color" if values.empty?
+
+        values
+      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
+    end
+  end
+end

data/lib/vizcore/dsl/mapping_resolver.rb

@@ -4,6 +4,10 @@ module Vizcore
   module DSL
     # Resolves `map` definitions into concrete per-layer parameter values.
     class MappingResolver
+      def initialize
+        @mapping_state = {}
+      end
+
       # @param scene_layers [Array<Hash>]
       # @param audio [Hash]
       # @return [Array<Hash>] normalized layer payloads with resolved params
@@ -17,7 +21,7 @@ module Vizcore
 
       def resolve_layer(layer, audio)
         params = (layer[:params] || {}).dup
-        params.merge!(resolve_mappings(layer[:mappings], audio))
+        merge_resolved_mappings!(params, resolve_mappings(layer[:mappings], audio, layer_name: layer[:name]))
 
         output = {
           name: layer.fetch(:name).to_s,
@@ -27,20 +31,64 @@ module Vizcore
         output[:shader] = layer[:shader].to_s if layer[:shader]
         output[:glsl] = layer[:glsl].to_s if layer[:glsl]
         output[:glsl_source] = layer[:glsl_source].to_s if layer[:glsl_source]
+        output[:param_schema] = Array(layer[:param_schema]).map(&:dup) if layer[:param_schema]
         output
       end
 
-      def resolve_mappings(mappings, audio)
+      def resolve_mappings(mappings, audio, layer_name:)
         Array(mappings).each_with_object({}) do |mapping, resolved|
           source = mapping[:source]
           target = mapping[:target]
           next unless source && target
 
           value = resolve_source_value(source, audio)
-          resolved[target.to_sym] = value unless value.nil?
+          value = apply_transform(value, mapping[:transform], state_key: [layer_name, target, source])
+          resolved[target.to_s] = value unless value.nil?
+        end
+      end
+
+      def merge_resolved_mappings!(params, mappings)
+        mappings.each do |target, value|
+          if target.include?(".")
+            assign_nested_param(params, target.split("."), value)
+          else
+            params[target.to_sym] = value
+          end
+        end
+      end
+
+      def assign_nested_param(container, path, value)
+        key = path.shift
+        if path.empty?
+          assign_nested_value(container, key, value)
+          return
+        end
+
+        next_container = nested_value(container, key)
+        return unless next_container
+
+        assign_nested_param(next_container, path, value)
+      end
+
+      def nested_value(container, key)
+        return container[key.to_i] if container.is_a?(Array) && integer_key?(key)
+        return container[key.to_sym] if container.is_a?(Hash)
+
+        nil
+      end
+
+      def assign_nested_value(container, key, value)
+        if container.is_a?(Array) && integer_key?(key)
+          container[key.to_i] = value
+        elsif container.is_a?(Hash)
+          container[key.to_sym] = value
         end
       end
 
+      def integer_key?(value)
+        value.match?(/\A\d+\z/)
+      end
+
       def resolve_source_value(source, audio)
         case source[:kind]&.to_sym
         when :amplitude
@@ -49,8 +97,16 @@ module Vizcore
           audio.dig(:bands, source[:band]&.to_sym)
         when :fft_spectrum
           audio[:fft]
+        when :onset
+          resolve_onset(source, audio)
+        when :kick, :snare, :hihat
+          audio.dig(:drums, source[:kind].to_sym)
         when :beat
           audio[:beat]
+        when :beat_confidence
+          audio[:beat_confidence]
+        when :beat_pulse
+          audio[:beat_pulse]
         when :beat_count
           audio[:beat_count]
         when :bpm
@@ -60,6 +116,79 @@ module Vizcore
         end
       end
 
+      def resolve_onset(source, audio)
+        band = source[:band]&.to_sym
+        return audio[:onset] unless band
+
+        audio.dig(:onsets, band)
+      end
+
+      def apply_transform(value, transform, state_key:)
+        return value if transform.nil? || transform.empty?
+        return transform_array(value, transform) if value.is_a?(Array)
+        return nil if value.is_a?(Hash) || value.nil?
+
+        transformed = transform_scalar(value, transform)
+        return nil if transformed.nil?
+
+        apply_smoothing(transformed, transform, state_key)
+      end
+
+      def transform_array(value, transform)
+        value.map do |entry|
+          transform_scalar(entry, transform, fallback: 0.0) || 0.0
+        end
+      end
+
+      def transform_scalar(value, transform, fallback: nil)
+        numeric = numeric_value(value, fallback: fallback)
+        return nil if numeric.nil?
+
+        numeric = 0.0 if transform.key?(:deadzone) && numeric.abs < Float(transform[:deadzone])
+        numeric *= Float(transform[:gain]) if transform.key?(:gain)
+        numeric = apply_curve(numeric, transform[:curve]) if transform[:curve]
+        numeric = [numeric, Float(transform[:min])].max if transform.key?(:min)
+        numeric = [numeric, Float(transform[:max])].min if transform.key?(:max)
+        numeric
+      end
+
+      def numeric_value(value, fallback:)
+        return value ? 1.0 : 0.0 if value == true || value == false
+
+        Float(value)
+      rescue ArgumentError, TypeError
+        fallback
+      end
+
+      def apply_curve(value, curve)
+        case curve.to_sym
+        when :linear
+          value
+        when :sqrt
+          Math.sqrt([value, 0.0].max)
+        when :square
+          value * value
+        when :ease_out
+          clamped = [[value, 0.0].max, 1.0].min
+          1.0 - ((1.0 - clamped) * (1.0 - clamped))
+        end
+      end
+
+      def apply_smoothing(value, transform, state_key)
+        return value unless transform.key?(:attack) || transform.key?(:release)
+
+        previous = @mapping_state[state_key]
+        if previous.nil?
+          @mapping_state[state_key] = value
+          return value
+        end
+
+        alpha = value >= previous ? transform.fetch(:attack, 1.0) : transform.fetch(:release, 1.0)
+        smoothed = previous + (value - previous) * alpha
+        @mapping_state[state_key] = smoothed
+        smoothed
+      end
+
       def normalize_scene_layers(scene_layers)
         Array(scene_layers).map { |layer| deep_symbolize(layer) }
       end

data/lib/vizcore/dsl/mapping_transform_builder.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Vizcore
+  module DSL
+    # Collects block-style mapping transform options.
+    class MappingTransformBuilder
+      # @param initial [Hash]
+      def initialize(initial = {})
+        @values = initial.each_with_object({}) do |(key, value), output|
+          output[key.to_sym] = value
+        end
+      end
+
+      # @return [Vizcore::DSL::MappingTransformBuilder]
+      def evaluate(&block)
+        instance_eval(&block) if block
+        self
+      end
+
+      # @param value [Numeric]
+      # @return [Numeric]
+      def gain(value)
+        @values[:gain] = value
+      end
+
+      # @param value [Range, Array]
+      # @return [Range, Array]
+      def range(value)
+        @values[:range] = value
+      end
+
+      # @param value [Numeric]
+      # @return [Numeric]
+      def min(value)
+        @values[:min] = value
+      end
+
+      # @param value [Numeric]
+      # @return [Numeric]
+      def max(value)
+        @values[:max] = value
+      end
+
+      # @param value [Symbol, String]
+      # @return [Symbol, String]
+      def curve(value)
+        @values[:curve] = value
+      end
+
+      # @param value [Numeric]
+      # @return [Numeric]
+      def deadzone(value)
+        @values[:deadzone] = value
+      end
+
+      # @param attack [Numeric, nil]
+      # @param release [Numeric, nil]
+      # @return [Hash]
+      def smooth(attack: nil, release: nil)
+        @values[:attack] = attack unless attack.nil?
+        @values[:release] = release unless release.nil?
+        @values
+      end
+
+      # @return [Hash]
+      def to_h
+        @values.dup
+      end
+    end
+  end
+end

data/lib/vizcore/dsl/reaction_builder.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Vizcore
+  module DSL
+    # Collects high-level `react_to` DSL entries and converts them to mappings.
+    class ReactionBuilder
+      # @param mapping_factory [#call] builds one normalized mapping hash
+      def initialize(mapping_factory:)
+        @mapping_factory = mapping_factory
+        @mappings = []
+      end
+
+      # Evaluate a `react_to` block.
+      #
+      # @yield Reaction DSL methods
+      # @raise [ArgumentError] when the block does not define any reaction
+      # @return [Array<Hash>] normalized mapping payloads
+      def evaluate(&block)
+        instance_eval(&block) if block
+        raise ArgumentError, "react_to requires at least one change or trigger" if @mappings.empty?
+
+        @mappings.map(&:dup)
+      end
+
+      # Continuously map the reaction source to a target parameter.
+      #
+      # @param target [Symbol, String] layer parameter name
+      # @param options [Hash] mapping transform options
+      # @return [void]
+      def change(target, **options)
+        @mappings << @mapping_factory.call(target, options)
+      end
+
+      # Map the reaction source to an event-like target parameter.
+      #
+      # @param target [Symbol, String] layer parameter name
+      # @param options [Hash] mapping transform options
+      # @return [void]
+      def trigger(target, **options)
+        change(target, **options)
+      end
+    end
+  end
+end

data/lib/vizcore/dsl/scene_builder.rb

@@ -1,15 +1,23 @@
 # frozen_string_literal: true
 
 require_relative "layer_builder"
+require_relative "layer_group_builder"
 
 module Vizcore
   module DSL
     # Collects layer definitions inside a single scene block.
     class SceneBuilder
       # @param name [Symbol, String] scene identifier
-      def initialize(name:)
+      # @param styles [Hash] reusable layer parameter styles
+      # @param themes [Hash] reusable scene-wide layer parameter themes
+      # @param layers [Array<Hash>] initial layer definitions
+      def initialize(name:, styles: {}, themes: {}, layers: [])
         @name = name.to_sym
-        @layers = []
+        @styles = styles
+        @themes = themes
+        @theme_name = nil
+        @theme_params = {}
+        @layers = layers.map { |layer| deep_dup(layer) }
       end
 
       # Evaluate a scene block.
@@ -27,17 +35,65 @@ module Vizcore
       # @yield Layer definition block
       # @return [void]
       def layer(name, &block)
-        builder = LayerBuilder.new(name: name)
+        builder = LayerBuilder.new(name: name, styles: @styles, defaults: @theme_params)
         builder.evaluate(&block)
         @layers << builder.to_h
       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.evaluate(&block)
+        @layers.concat(builder.to_a)
+      end
+
+      # Apply a named theme as default params for all layers in this scene.
+      #
+      # @param name [Symbol, String] theme identifier
+      # @raise [ArgumentError] when the theme is unknown
+      # @return [Hash] applied theme params
+      def use_theme(name)
+        theme_name = name.to_sym
+        theme_params = @themes.fetch(theme_name) { raise ArgumentError, "unknown theme: #{theme_name}" }
+        @theme_name = theme_name
+        @theme_params = deep_dup(theme_params)
+        @layers = @layers.map { |layer| apply_theme_defaults(layer, @theme_params) }
+        deep_dup(@theme_params)
+      end
+
       # @return [Hash] serialized scene payload
       def to_h
-        {
+        scene = {
           name: @name,
-          layers: @layers.map { |layer| layer.dup }
+          layers: @layers.map { |layer| deep_dup(layer) }
         }
+        scene[:theme] = @theme_name if @theme_name
+        scene
+      end
+
+      private
+
+      def apply_theme_defaults(layer, theme_params)
+        themed_layer = deep_dup(layer)
+        themed_layer[:params] = deep_dup(theme_params).merge(Hash(themed_layer[:params] || {}))
+        themed_layer
+      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
     end
   end

data/lib/vizcore/dsl/shader_source_resolver.rb

@@ -1,15 +1,28 @@
 # frozen_string_literal: true
 
+require "base64"
 require "pathname"
 
 module Vizcore
   module DSL
-    # Replaces layer `glsl` paths with inlined shader source text.
+    # Replaces external layer source paths with browser-ready inline payloads.
     class ShaderSourceResolver
+      MEDIA_MIME_TYPES = {
+        ".gif" => "image/gif",
+        ".jpg" => "image/jpeg",
+        ".jpeg" => "image/jpeg",
+        ".png" => "image/png",
+        ".svg" => "image/svg+xml",
+        ".webp" => "image/webp",
+        ".mp4" => "video/mp4",
+        ".ogv" => "video/ogg",
+        ".webm" => "video/webm"
+      }.freeze
+
       # @param definition [Hash] DSL definition payload
       # @param scene_file [String, Pathname] source scene file
-      # @raise [ArgumentError] when a referenced GLSL file is missing
-      # @return [Hash] deep-copied definition with `:glsl_source` entries
+      # @raise [ArgumentError] when a referenced source file is missing
+      # @return [Hash] deep-copied definition with resolved layer source entries
       def resolve(definition:, scene_file:)
         scene_path = Pathname.new(scene_file.to_s).expand_path
         base_dir = scene_path.dirname
@@ -29,8 +42,13 @@ module Vizcore
       def resolve_layer(layer, base_dir:)
         layer_hash = symbolize_hash(layer)
         shader_path = layer_hash[:glsl]
-        return layer_hash unless shader_path
+        layer_hash = resolve_shader_layer(layer_hash, base_dir: base_dir) if shader_path
+        layer_hash = resolve_media_layer(layer_hash, base_dir: base_dir) if media_layer?(layer_hash)
+        layer_hash
+      end
 
+      def resolve_shader_layer(layer_hash, base_dir:)
+        shader_path = layer_hash.fetch(:glsl)
         full_path = resolve_path(base_dir: base_dir, shader_path: shader_path)
         raise ArgumentError, "GLSL file not found: #{shader_path}" unless full_path.file?
 
@@ -39,8 +57,51 @@ module Vizcore
         layer_hash
       end
 
-      def resolve_path(base_dir:, shader_path:)
-        path = Pathname.new(shader_path.to_s)
+      def resolve_media_layer(layer_hash, base_dir:)
+        params = symbolize_hash(layer_hash[:params] || {})
+        media_path = params[:file]
+        return layer_hash unless media_path
+
+        full_path = resolve_path(base_dir: base_dir, relative_path: media_path)
+        raise ArgumentError, "#{media_layer_label(layer_hash)} file not found: #{media_path}" unless full_path.file?
+
+        mime_type = MEDIA_MIME_TYPES[full_path.extname.downcase]
+        raise ArgumentError, "Unsupported #{media_layer_label(layer_hash)} file extension: #{media_path}" unless mime_type
+        raise ArgumentError, "Unsupported SVG file extension: #{media_path}" if svg_layer?(layer_hash) && mime_type != "image/svg+xml"
+        raise ArgumentError, "Unsupported Image file extension: #{media_path}" if image_layer?(layer_hash) && !mime_type.start_with?("image/")
+        raise ArgumentError, "Unsupported Video file extension: #{media_path}" if video_layer?(layer_hash) && !mime_type.start_with?("video/")
+
+        params[:file] = media_path.to_s
+        params[:src] = "data:#{mime_type};base64,#{Base64.strict_encode64(full_path.binread)}"
+        layer_hash[:params] = params
+        layer_hash
+      end
+
+      def svg_layer?(layer_hash)
+        %i[svg svg_layer].include?(layer_hash[:type]&.to_sym)
+      end
+
+      def image_layer?(layer_hash)
+        %i[image image_layer photo].include?(layer_hash[:type]&.to_sym)
+      end
+
+      def video_layer?(layer_hash)
+        %i[video video_layer footage].include?(layer_hash[:type]&.to_sym)
+      end
+
+      def media_layer?(layer_hash)
+        svg_layer?(layer_hash) || image_layer?(layer_hash) || video_layer?(layer_hash)
+      end
+
+      def media_layer_label(layer_hash)
+        return "SVG" if svg_layer?(layer_hash)
+        return "Video" if video_layer?(layer_hash)
+
+        "Image"
+      end
+
+      def resolve_path(base_dir:, relative_path: nil, shader_path: nil)
+        path = Pathname.new((relative_path || shader_path).to_s)
         return path.expand_path if path.absolute?
 
         base_dir.join(path).expand_path

data/lib/vizcore/dsl/style_builder.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Vizcore
+  module DSL
+    # Collects reusable layer parameter presets for the `style` DSL.
+    class StyleBuilder
+      # @param name [Symbol, String] style identifier
+      # @param kind [String] user-facing DSL kind for error messages
+      def initialize(name:, kind: "style")
+        @name = name.to_sym
+        @kind = kind
+        @params = {}
+      end
+
+      # Evaluate a style block.
+      #
+      # @yield Style parameter declarations
+      # @return [Vizcore::DSL::StyleBuilder]
+      def evaluate(&block)
+        instance_eval(&block) if block
+        raise ArgumentError, "#{@kind} #{@name} requires at least one parameter" if @params.empty?
+
+        self
+      end
+
+      # @return [Hash] serialized style payload
+      def to_h
+        {
+          name: @name,
+          params: @params.dup
+        }
+      end
+
+      # Store an ordered color palette for styles and themes.
+      #
+      # @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
+
+      # Stores one-argument style setters into `params`.
+      # @api private
+      def method_missing(method_name, *args, &block)
+        if block.nil? && args.length == 1
+          @params[method_name.to_sym] = args.first
+          return args.first
+        end
+
+        super
+      end
+
+      def respond_to_missing?(_method_name, _include_private = false)
+        true
+      end
+
+      private
+
+      def normalize_palette(colors)
+        values = colors.flatten.map { |color| color.to_s.strip }.reject(&:empty?)
+        raise ArgumentError, "#{@kind} #{@name} palette requires at least one color" if values.empty?
+
+        values
+      end
+    end
+  end
+end