vizcore 0.1.0 → 1.1.0

data/lib/vizcore/cli/scene_validator.rb

@@ -0,0 +1,337 @@
+# frozen_string_literal: true
+
+require "set"
+require_relative "../../vizcore"
+require_relative "../dsl"
+require_relative "../layer_catalog"
+
+module Vizcore
+  module CLISupport
+    # Validates scene DSL files without starting the realtime server.
+    class SceneValidator
+      BUILTIN_SHADERS = Vizcore::LayerCatalog::BUILTIN_SHADERS
+
+      MAPPING_SOURCE_KINDS = %i[
+        amplitude frequency_band fft_spectrum onset kick snare hihat beat beat_confidence beat_pulse beat_count bpm
+      ].freeze
+
+      FREQUENCY_BANDS = %i[sub low mid high].freeze
+      SUPPORTED_BLEND_MODES = Vizcore::LayerCatalog::BLEND_MODES
+      SUPPORTED_POST_EFFECTS = Vizcore::LayerCatalog::POST_EFFECTS
+      SUPPORTED_VJ_EFFECTS = Vizcore::LayerCatalog::VJ_EFFECTS
+      SUPPORTED_SHAPE_KINDS = %i[circle line rect polygon polyline path star].freeze
+
+      Issue = Struct.new(:severity, :message, keyword_init: true) do
+        def error?
+          severity == :error
+        end
+      end
+
+      Result = Struct.new(:definition, :issues, keyword_init: true) do
+        def valid?
+          issues.none?(&:error?)
+        end
+
+        def errors
+          issues.select(&:error?)
+        end
+
+        def warnings
+          issues.reject(&:error?)
+        end
+      end
+
+      def initialize(scene_file:, loader: Vizcore::DSL::Engine.method(:load_file), shader_resolver: Vizcore::DSL::ShaderSourceResolver.new)
+        @scene_file = scene_file
+        @loader = loader
+        @shader_resolver = shader_resolver
+      end
+
+      def call
+        definition = load_definition
+        Result.new(definition: definition, issues: validate_definition(definition))
+      rescue StandardError => e
+        Result.new(
+          definition: nil,
+          issues: [Issue.new(severity: :error, message: "failed to load scene: #{e.message}")]
+        )
+      end
+
+      private
+
+      def load_definition
+        definition = @loader.call(@scene_file)
+        @shader_resolver.resolve(definition: definition, scene_file: @scene_file)
+      end
+
+      def validate_definition(definition)
+        issues = []
+        scenes = Array(definition[:scenes])
+        validate_scenes(scenes, issues)
+        names = scene_names(scenes)
+        validate_transitions(Array(definition[:transitions]), names, issues)
+        validate_key_mappings(Array(definition[:key_mappings]), names, issues)
+        issues
+      end
+
+      def validate_scenes(scenes, issues)
+        issues << error("no scenes defined") if scenes.empty?
+        duplicate_values(scenes.filter_map { |scene| scene[:name]&.to_sym }).each do |name|
+          issues << error("duplicate scene name: #{name}")
+        end
+
+        scenes.each do |scene|
+          scene_name = scene[:name] || "(unnamed)"
+          layers = Array(scene[:layers])
+          issues << warn("scene #{scene_name} has no layers; frontend will render the default geometry") if layers.empty?
+          validate_layers(layers, scene_name, issues)
+        end
+      end
+
+      def validate_layers(layers, scene_name, issues)
+        duplicate_values(layers.filter_map { |layer| layer[:name]&.to_sym }).each do |name|
+          issues << warn("scene #{scene_name} has duplicate layer name: #{name}")
+        end
+
+        layers.each do |layer|
+          validate_layer(layer, scene_name, issues)
+        end
+      end
+
+      def validate_layer(layer, scene_name, issues)
+        layer_name = layer[:name] || "(unnamed)"
+        type = layer[:type]&.to_sym || :geometry
+        unless supported_layer_types.include?(type)
+          issues << error("scene #{scene_name} layer #{layer_name} has unsupported type: #{type}")
+        end
+
+        shader = layer[:shader]&.to_sym
+        if shader && !BUILTIN_SHADERS.include?(shader)
+          issues << error("scene #{scene_name} layer #{layer_name} uses unknown shader: #{shader}")
+        end
+
+        glsl_source = layer[:glsl_source]
+        issues << warn("scene #{scene_name} layer #{layer_name} has an empty GLSL file") if layer[:glsl] && glsl_source.to_s.empty?
+        validate_blend_mode(layer, scene_name, layer_name, issues)
+        validate_layer_effects(layer, scene_name, layer_name, issues)
+        validate_shape_layer(layer, scene_name, layer_name, issues)
+        validate_mappings(Array(layer[:mappings]), scene_name, layer_name, issues)
+      end
+
+      def validate_blend_mode(layer, scene_name, layer_name, issues)
+        blend = layer.dig(:params, :blend)
+        return unless blend
+        return if SUPPORTED_BLEND_MODES.include?(blend.to_sym)
+
+        issues << error("scene #{scene_name} layer #{layer_name} uses unsupported blend mode: #{blend}")
+      end
+
+      def validate_layer_effects(layer, scene_name, layer_name, issues)
+        params = layer[:params] || {}
+        validate_effect_name(params[:effect], SUPPORTED_POST_EFFECTS, "effect", scene_name, layer_name, issues)
+        validate_effect_name(params[:vj_effect], SUPPORTED_VJ_EFFECTS, "vj_effect", scene_name, layer_name, issues)
+      end
+
+      def validate_shape_layer(layer, scene_name, layer_name, issues)
+        params = layer[:params] || {}
+        return unless shape_layer?(layer) || shape_value(params, :shapes)
+
+        Array(shape_value(params, :shapes)).each_with_index do |shape, index|
+          values = shape_hash(shape)
+          label = shape_label(values, index)
+          validate_shape_kind(values, label, scene_name, layer_name, issues)
+          validate_shape_fallback_fill(values, label, scene_name, layer_name, issues)
+          validate_shape_opacity(values, label, scene_name, layer_name, issues)
+          validate_shape_scale(values, label, scene_name, layer_name, issues)
+        end
+      end
+
+      def validate_shape_kind(shape, label, scene_name, layer_name, issues)
+        kind = shape_value(shape, :kind)&.to_sym
+        return if SUPPORTED_SHAPE_KINDS.include?(kind)
+
+        issues << warn("scene #{scene_name} layer #{layer_name} shape #{label} uses unsupported kind: #{kind || "missing"}")
+      end
+
+      def validate_shape_fallback_fill(shape, label, scene_name, layer_name, issues)
+        fill = shape_value(shape, :fill)
+        return if fill.nil? || fill.to_s.empty?
+
+        issues << warn("scene #{scene_name} layer #{layer_name} shape #{label} fill may be ignored by line fallback")
+      end
+
+      def validate_shape_opacity(shape, label, scene_name, layer_name, issues)
+        opacity = numeric_shape_value(shape_value(shape, :opacity))
+        return unless opacity && (opacity.negative? || opacity > 1)
+
+        issues << warn("scene #{scene_name} layer #{layer_name} shape #{label} opacity #{opacity} is outside 0..1; renderer will clamp")
+      end
+
+      def validate_shape_scale(shape, label, scene_name, layer_name, issues)
+        scale_values(shape).each do |scale|
+          next unless scale
+
+          if scale.zero?
+            issues << warn("scene #{scene_name} layer #{layer_name} shape #{label} scale includes 0; shape may collapse")
+          elsif scale.abs > 8
+            issues << warn("scene #{scene_name} layer #{layer_name} shape #{label} scale #{scale} is extreme; renderer will clamp")
+          end
+        end
+      end
+
+      def supported_layer_types
+        Vizcore::LayerCatalog.supported_types
+      end
+
+      def shape_layer?(layer)
+        %w[shape shapes shape_layer].include?((layer[:type] || layer["type"]).to_s)
+      end
+
+      def shape_label(shape, index)
+        id = shape_value(shape, :id)
+        id ? "`#{id}`" : "##{index + 1}"
+      end
+
+      def scale_values(shape)
+        transform = Hash(shape_value(shape, :transform) || {})
+        scale = shape_value(transform, :scale) || shape_value(shape, :scale)
+        case scale
+        when Hash
+          [numeric_shape_value(shape_value(scale, :x)), numeric_shape_value(shape_value(scale, :y))]
+        when Array
+          [numeric_shape_value(scale[0]), numeric_shape_value(scale[1])]
+        else
+          [numeric_shape_value(scale)]
+        end
+      rescue TypeError
+        []
+      end
+
+      def numeric_shape_value(value)
+        return nil if value.nil?
+
+        numeric = Float(value)
+        numeric if numeric.finite?
+      rescue ArgumentError, TypeError
+        nil
+      end
+
+      def shape_hash(value)
+        Hash(value)
+      rescue TypeError
+        {}
+      end
+
+      def shape_value(hash, key)
+        hash[key] || hash[key.to_s]
+      end
+
+      def validate_effect_name(value, supported, field, scene_name, layer_name, issues)
+        return unless value
+        return if supported.include?(value.to_sym)
+
+        issues << error("scene #{scene_name} layer #{layer_name} uses unsupported #{field}: #{value}")
+      end
+
+      def validate_mappings(mappings, scene_name, layer_name, issues)
+        mappings.each do |mapping|
+          source = Hash(mapping[:source] || {})
+          kind = source[:kind]&.to_sym
+          issues << error("scene #{scene_name} layer #{layer_name} has mapping without source kind") unless kind
+          next unless kind
+
+          validate_mapping_source(kind, source, scene_name, layer_name, issues)
+          issues << error("scene #{scene_name} layer #{layer_name} has mapping without target") unless mapping[:target]
+          validate_transform(Hash(mapping[:transform] || {}), scene_name, layer_name, mapping[:target], issues)
+        end
+      end
+
+      def validate_mapping_source(kind, source, scene_name, layer_name, issues)
+        unless MAPPING_SOURCE_KINDS.include?(kind)
+          issues << error("scene #{scene_name} layer #{layer_name} uses unsupported mapping source: #{kind}")
+        end
+        validate_frequency_band(source, scene_name, layer_name, issues) if kind == :frequency_band
+        validate_onset_band(source, scene_name, layer_name, issues) if kind == :onset
+      end
+
+      def validate_frequency_band(source, scene_name, layer_name, issues)
+        band = source[:band]&.to_sym
+        return if FREQUENCY_BANDS.include?(band)
+
+        issues << error("scene #{scene_name} layer #{layer_name} uses unsupported frequency band: #{band.inspect}")
+      end
+
+      def validate_onset_band(source, scene_name, layer_name, issues)
+        return unless source.key?(:band)
+
+        band = source[:band]&.to_sym
+        return if FREQUENCY_BANDS.include?(band)
+
+        issues << error("scene #{scene_name} layer #{layer_name} uses unsupported onset band: #{band.inspect}")
+      end
+
+      def validate_transform(transform, scene_name, layer_name, target, issues)
+        return unless transform.key?(:min) && transform.key?(:max)
+        return unless Float(transform[:min]) > Float(transform[:max])
+
+        issues << error("scene #{scene_name} layer #{layer_name} mapping #{target} has min greater than max")
+      rescue ArgumentError, TypeError
+        issues << error("scene #{scene_name} layer #{layer_name} mapping #{target} has non-numeric min/max")
+      end
+
+      def validate_transitions(transitions, names, issues)
+        transitions.each do |transition|
+          from = transition[:from]&.to_sym
+          to = transition[:to]&.to_sym
+          issues << error("transition has unknown source scene: #{from}") if from && !names.include?(from)
+          issues << error("transition has unknown target scene: #{to}") if to && !names.include?(to)
+          unless transition[:trigger].respond_to?(:call)
+            issues << warn("transition #{from || '?'} -> #{to || '?'} has no trigger block")
+          end
+        end
+      end
+
+      def validate_key_mappings(mappings, names, issues)
+        mappings.each do |mapping|
+          key = mapping[:key] || mapping["key"]
+          action = mapping[:action] || mapping["action"]
+          issues << error("key mapping has empty key") if key.to_s.strip.empty?
+          validate_key_action(action.is_a?(Hash) ? action : {}, names, key, issues)
+        end
+      end
+
+      def validate_key_action(action, names, key, issues)
+        type = (action[:type] || action["type"]).to_s.to_sym
+        case type
+        when :switch_scene
+          scene = action[:scene] || action["scene"]
+          scene_name = scene&.to_sym
+          issues << error("key #{key} switches to unknown scene: #{scene}") unless scene_name && names.include?(scene_name)
+        when :live_control
+          control = (action[:control] || action["control"]).to_s.to_sym
+          issues << error("key #{key} uses unsupported live control: #{control}") unless %i[blackout freeze].include?(control)
+        else
+          issues << error("key #{key} has unsupported action: #{type}")
+        end
+      end
+
+      def scene_names(scenes)
+        scenes.filter_map { |scene| scene[:name]&.to_sym }.to_set
+      end
+
+      def duplicate_values(values)
+        counts = Hash.new(0)
+        values.each { |value| counts[value] += 1 }
+        counts.select { |_value, count| count > 1 }.keys
+      end
+
+      def error(message)
+        Issue.new(severity: :error, message: message)
+      end
+
+      def warn(message)
+        Issue.new(severity: :warn, message: message)
+      end
+    end
+  end
+end

data/lib/vizcore/cli/shader_template.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "pathname"
+
+module Vizcore
+  module CLISupport
+    # Writes starter GLSL ES fragment shaders for custom shader layers.
+    class ShaderTemplate
+      TEMPLATE = <<~GLSL
+        #version 300 es
+        precision highp float;
+
+        uniform vec2 u_resolution;
+        uniform float u_time;
+        uniform float u_amplitude;
+        uniform float u_bass;
+        uniform float u_mid;
+        uniform float u_high;
+        uniform float u_beat;
+        uniform float u_beat_pulse;
+        uniform float u_onset;
+        uniform float u_kick;
+        uniform float u_bpm;
+        uniform float u_fft[32];
+        uniform float u_fft_size;
+
+        out vec4 outColor;
+
+        void main() {
+          vec2 uv = gl_FragCoord.xy / u_resolution.xy;
+          float wave = 0.5 + 0.5 * sin((uv.x + u_time * 0.12) * 12.0 + u_bass * 4.0);
+          vec3 color = mix(vec3(0.02, 0.06, 0.12), vec3(0.1, 0.75, 0.95), wave);
+          color += vec3(0.95, 0.16, 0.32) * (u_beat_pulse * 0.35 + u_onset * 0.2 + u_kick * 0.25 + u_high * 0.2);
+          color *= 0.35 + u_amplitude * 1.8;
+          outColor = vec4(color, 1.0);
+        }
+      GLSL
+
+      # @param name [String]
+      # @return [String]
+      def self.default_path(name)
+        "shaders/#{safe_name(name)}.frag"
+      end
+
+      # @param name [String]
+      # @return [String]
+      def self.safe_name(name)
+        raw_name = name.to_s.strip.sub(/\.frag\z/i, "")
+        safe = raw_name.gsub(/[^a-zA-Z0-9_-]+/, "_").gsub(/\A_+|_+\z/, "")
+        raise ArgumentError, "shader name is required" if safe.empty?
+
+        safe
+      end
+
+      # @param path [String, Pathname]
+      # @return [Pathname]
+      def write(path)
+        destination = Pathname(path)
+        raise ArgumentError, "Shader file already exists: #{destination}" if destination.exist?
+
+        FileUtils.mkdir_p(destination.dirname)
+        destination.write(TEMPLATE)
+        destination
+      end
+    end
+  end
+end

data/lib/vizcore/cli/shader_uniform_docs.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Vizcore
+  module CLISupport
+    # Produces the custom GLSL uniform reference used by CLI and docs.
+    class ShaderUniformDocs
+      Uniform = Struct.new(:name, :type, :description, keyword_init: true)
+
+      UNIFORMS = [
+        Uniform.new(name: "u_resolution", type: "vec2", description: "Canvas size in pixels as width and height."),
+        Uniform.new(name: "u_time", type: "float", description: "Renderer time in seconds."),
+        Uniform.new(name: "u_amplitude", type: "float", description: "Normalized RMS amplitude, usually 0.0..1.0."),
+        Uniform.new(name: "u_bass", type: "float", description: "Low-frequency band level."),
+        Uniform.new(name: "u_mid", type: "float", description: "Mid-frequency band level."),
+        Uniform.new(name: "u_high", type: "float", description: "High-frequency band level."),
+        Uniform.new(name: "u_beat", type: "float", description: "1.0 on detected beat frames, otherwise 0.0."),
+        Uniform.new(name: "u_beat_pulse", type: "float", description: "Decaying beat pulse after detection."),
+        Uniform.new(name: "u_onset", type: "float", description: "Positive amplitude rise since the previous active frame."),
+        Uniform.new(name: "u_sub_onset", type: "float", description: "Positive sub-band rise since the previous active frame."),
+        Uniform.new(name: "u_low_onset", type: "float", description: "Positive low-band rise since the previous active frame."),
+        Uniform.new(name: "u_mid_onset", type: "float", description: "Positive mid-band rise since the previous active frame."),
+        Uniform.new(name: "u_high_onset", type: "float", description: "Positive high-band rise since the previous active frame."),
+        Uniform.new(name: "u_kick", type: "float", description: "Low-band percussive confidence derived from band level and onset."),
+        Uniform.new(name: "u_snare", type: "float", description: "Mid-band percussive confidence derived from band level and onset."),
+        Uniform.new(name: "u_hihat", type: "float", description: "High-band percussive confidence derived from band level and onset."),
+        Uniform.new(name: "u_bpm", type: "float", description: "Current BPM estimate, or 0.0 when unavailable."),
+        Uniform.new(name: "u_fft[32]", type: "float[]", description: "Normalized FFT preview bins."),
+        Uniform.new(name: "u_fft_size", type: "float", description: "Number of populated FFT preview bins."),
+        Uniform.new(name: "u_visual_gain", type: "float", description: "Browser visual gain control value."),
+        Uniform.new(name: "u_bass_boost", type: "float", description: "Browser bass boost control value."),
+        Uniform.new(name: "u_wobble_amount", type: "float", description: "Browser wobble amount control value."),
+        Uniform.new(name: "u_param_<name>", type: "float", description: "Numeric layer param or mapped DSL target."),
+        Uniform.new(name: "u_global_<name>", type: "float", description: "Numeric runtime global from DSL or MIDI set.")
+      ].freeze
+
+      # @return [Array<String>]
+      def lines
+        [
+          "# Vizcore Shader Uniforms",
+          "",
+          "Custom fragment shaders use GLSL ES 3.00 and receive these uniforms:",
+          "",
+          "| Uniform | Type | Description |",
+          "| --- | --- | --- |",
+          *UNIFORMS.map { |uniform| "| `#{uniform.name}` | `#{uniform.type}` | #{uniform.description} |" },
+          "",
+          "Layer params are exposed as `u_param_<name>` after non-word characters are converted to underscores.",
+          "For compatibility, a mapped target like `:param_intensity` is also exposed as `u_param_intensity`.",
+          "Runtime globals are exposed as `u_global_<name>`; `:global_intensity` becomes `u_global_intensity`."
+        ]
+      end
+    end
+  end
+end