vizcore 1.0.0 → 1.2.0

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

data/lib/vizcore/dsl/transition_controller.rb

@@ -8,7 +8,9 @@ module Vizcore
 
       # @param scenes [Array<Hash>]
       # @param transitions [Array<Hash>]
-      def initialize(scenes:, transitions:)
+      # @param error_reporter [#call, nil]
+      def initialize(scenes:, transitions:, error_reporter: nil)
+        @error_reporter = error_reporter || ->(_message) {}
         update(scenes: scenes, transitions: transitions)
       end
 
@@ -23,11 +25,12 @@ module Vizcore
       # @param scene_name [String, Symbol]
       # @param audio [Hash]
       # @param frame_count [Integer]
+      # @param elapsed_seconds [Numeric, nil]
       # @return [Hash, nil] transition payload when condition matches
-      def next_transition(scene_name:, audio:, frame_count: 0)
+      def next_transition(scene_name:, audio:, frame_count: 0, elapsed_seconds: nil)
         current = scene_name.to_sym
         transition = @transitions.find do |entry|
-          entry[:from] == current && trigger_match?(entry[:trigger], audio, frame_count)
+          entry[:from] == current && trigger_match?(entry, audio, frame_count, elapsed_seconds)
         end
         return nil unless transition
 
@@ -73,14 +76,24 @@ module Vizcore
         end
       end
 
-      def trigger_match?(trigger, audio, frame_count)
+      def trigger_match?(transition, audio, frame_count, elapsed_seconds)
+        trigger = transition[:trigger]
         return false unless trigger.respond_to?(:call)
 
-        TriggerContext.new(audio, frame_count: frame_count).instance_exec(&trigger)
-      rescue StandardError
+        TriggerContext.new(audio, frame_count: frame_count, elapsed_seconds: elapsed_seconds).instance_exec(&trigger)
+      rescue StandardError => e
+        report_trigger_error(transition, e)
         false
       end
 
+      def report_trigger_error(transition, error)
+        @error_reporter.call(
+          "transition trigger failed: #{transition[:from]} -> #{transition[:to]} (#{error.class}: #{error.message})"
+        )
+      rescue StandardError
+        nil
+      end
+
       def symbolize_hash(value)
         Hash(value).each_with_object({}) do |(key, entry), output|
           output[key.to_sym] = entry
@@ -90,16 +103,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 exposed to transition trigger blocks.
@@ -107,14 +111,18 @@ module Vizcore
       class TriggerContext
         # @param audio [Hash]
         # @param frame_count [Integer]
-        def initialize(audio, frame_count:)
+        # @param elapsed_seconds [Numeric, nil]
+        def initialize(audio, frame_count:, elapsed_seconds: nil)
           @audio = symbolize_hash(audio)
           @bands = symbolize_hash(@audio[:bands])
+          @band_peaks = symbolize_hash(@audio[:band_peaks])
           @onsets = symbolize_hash(@audio[:onsets])
           @drums = symbolize_hash(@audio[:drums])
           @frame_count = Integer(frame_count)
+          @elapsed_seconds = normalize_elapsed_seconds(elapsed_seconds)
         rescue StandardError
           @frame_count = 0
+          @elapsed_seconds = nil
         end
 
         # @return [Float]
@@ -122,42 +130,83 @@ module Vizcore
           @audio[:amplitude].to_f
         end
 
+        # @return [Float]
+        def peak
+          @audio[:peak].to_f
+        end
+
         # @param name [Symbol, String]
         # @return [Float]
         def frequency_band(name)
           @bands[name.to_sym].to_f
         end
 
+        # @param name [Symbol, String]
+        # @return [Float]
+        def frequency_band_peak(name)
+          @band_peaks[name.to_sym].to_f
+        end
+
         # @return [Float]
         def sub
           frequency_band(:sub)
         end
 
+        # @return [Float]
+        def sub_peak
+          frequency_band_peak(:sub)
+        end
+
         # @return [Float]
         def low
           frequency_band(:low)
         end
 
+        # @return [Float]
+        def low_peak
+          frequency_band_peak(:low)
+        end
+
         # @return [Float]
         def bass
           frequency_band(:low)
         end
 
+        # @return [Float]
+        def bass_peak
+          frequency_band_peak(:low)
+        end
+
         # @return [Float]
         def mid
           frequency_band(:mid)
         end
 
+        # @return [Float]
+        def mid_peak
+          frequency_band_peak(:mid)
+        end
+
         # @return [Float]
         def high
           frequency_band(:high)
         end
 
+        # @return [Float]
+        def high_peak
+          frequency_band_peak(:high)
+        end
+
         # @return [Float]
         def treble
           frequency_band(:high)
         end
 
+        # @return [Float]
+        def treble_peak
+          frequency_band_peak(:high)
+        end
+
         # @return [Array<Float>]
         def fft_spectrum
           Array(@audio[:fft])
@@ -213,23 +262,113 @@ module Vizcore
           0
         end
 
+        # @return [Float]
+        def beat_phase
+          @audio[:beat_phase].to_f
+        end
+
+        # @return [Boolean]
+        def beat_2
+          !!@audio[:beat_2]
+        end
+
+        # @return [Boolean]
+        def beat_4
+          !!@audio[:beat_4]
+        end
+
+        # @return [Boolean]
+        def beat_8
+          !!@audio[:beat_8]
+        end
+
+        # @return [Boolean]
+        def beat_triplet
+          !!@audio[:beat_triplet]
+        end
+
+        # @return [Boolean]
+        def triplet
+          beat_triplet
+        end
+
+        # @return [Float]
+        def bar_phase
+          @audio[:bar_phase].to_f
+        end
+
+        # @return [Integer]
+        def bar_count
+          Integer(@audio[:bar_count] || 0)
+        rescue StandardError
+          0
+        end
+
+        # @return [Integer]
+        def phrase_count
+          Integer(@audio[:phrase_count] || 0)
+        rescue StandardError
+          0
+        end
+
         # @return [Float]
         def bpm
           @audio[:bpm].to_f
         end
 
+        # @return [Float]
+        def bpm_confidence
+          @audio[:bpm_confidence].to_f
+        end
+
+        # @return [Float]
+        def spectral_centroid
+          @audio[:spectral_centroid].to_f
+        end
+
+        # @return [Float]
+        def spectral_rolloff
+          @audio[:spectral_rolloff].to_f
+        end
+
+        # @return [Float]
+        def spectral_flatness
+          @audio[:spectral_flatness].to_f
+        end
+
+        # @return [Float]
+        def spectral_flux
+          @audio[:spectral_flux].to_f
+        end
+
+        # @return [Float]
+        def zero_crossing_rate
+          @audio[:zero_crossing_rate].to_f
+        end
+
         # @return [Integer]
         def frame_count
           @frame_count
         end
 
-        # @return [Float] scene-local elapsed seconds at the default runtime frame rate
+        # @return [Float] scene-local elapsed seconds
         def seconds
+          return @elapsed_seconds if @elapsed_seconds
+
           @frame_count / DEFAULT_FRAME_RATE
         end
 
         private
 
+        def normalize_elapsed_seconds(value)
+          return nil if value.nil?
+
+          numeric = Float(value)
+          numeric.finite? ? numeric : nil
+        rescue StandardError
+          nil
+        end
+
         def symbolize_hash(value)
           Hash(value).each_with_object({}) do |(key, entry), output|
             output[key.to_sym] = entry

data/lib/vizcore/dsl.rb

@@ -6,11 +6,13 @@ module Vizcore
   end
 end
 
+require_relative "deep_copy"
 require_relative "dsl/file_watcher"
 require_relative "dsl/mapping_resolver"
 require_relative "dsl/mapping_transform_builder"
 require_relative "dsl/midi_map_executor"
 require_relative "dsl/reaction_builder"
+require_relative "dsl/mapping_preset_builder"
 require_relative "dsl/style_builder"
 require_relative "dsl/layer_builder"
 require_relative "dsl/scene_builder"

data/lib/vizcore/layer_catalog.rb

@@ -19,6 +19,7 @@ module Vizcore
       opacity: "Float",
       blend: "Symbol",
       effect: "Symbol",
+      post_effects: "Array<Symbol>",
       effect_intensity: "Float",
       vj_effect: "Symbol",
       palette: "Array<String>",
@@ -151,10 +152,12 @@ module Vizcore
         aliases: %i[shapes shape_layer],
         params: COMMON_PARAMS.merge(
           shapes: "Array<Hash>",
+          shape_schema_version: "Integer",
+          units: "Symbol",
           color_shift: "Float"
         ),
-        mappable_params: %i[color_shift opacity],
-        description: "Declarative 2D circle and line primitives rendered by the browser."
+        mappable_params: %i[color_shift opacity shapes],
+        description: "Declarative and Ruby-generated 2D circle, line, rect, polygon, polyline, path, and star primitives rendered by the browser."
       ),
       Capability.new(
         type: :mesh,

data/lib/vizcore/plugin_asset_policy.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "rack"
+
+module Vizcore
+  # Validates browser-side plugin assets before they are served by the runtime.
+  class PluginAssetPolicy
+    ALLOWED_EXTENSIONS = %w[.js .mjs].freeze
+    ALLOWED_MIME_TYPES = %w[text/javascript application/javascript].freeze
+
+    # @param path [String, Pathname]
+    # @param root [String, Pathname, nil] optional sandbox root
+    # @return [Pathname]
+    def self.validate!(path, root: nil)
+      asset_path = Pathname.new(path).expand_path
+      root_path = root ? Pathname.new(root).expand_path : nil
+
+      if root_path && !inside_root?(asset_path, root_path)
+        raise ArgumentError, "Plugin asset must stay inside #{root_path}: #{asset_path}"
+      end
+
+      unless ALLOWED_EXTENSIONS.include?(asset_path.extname.downcase)
+        raise ArgumentError, "Unsupported plugin asset extension: #{asset_path.extname}. Use one of: #{ALLOWED_EXTENSIONS.join(', ')}"
+      end
+
+      extname = asset_path.extname.downcase
+      mime_type = Rack::Mime.mime_type(extname, "application/octet-stream")
+      mime_type = case extname
+      when ".mjs"
+        mime_type == "application/octet-stream" ? "application/javascript" : mime_type
+      when ".js"
+        mime_type == "application/octet-stream" ? "text/javascript" : mime_type
+      else
+        mime_type
+      end
+      unless ALLOWED_MIME_TYPES.include?(mime_type)
+        raise ArgumentError, "Unsupported plugin asset MIME type: #{mime_type}. Use one of: #{ALLOWED_MIME_TYPES.join(", ")}"
+      end
+
+      asset_path
+    end
+
+    # @param path [Pathname]
+    # @param root [Pathname]
+    # @return [Boolean]
+    def self.inside_root?(path, root)
+      relative = path.relative_path_from(root)
+      !relative.each_filename.first&.start_with?("..")
+    rescue ArgumentError
+      false
+    end
+    private_class_method :inside_root?
+  end
+end

data/lib/vizcore/project_manifest.rb

@@ -2,6 +2,7 @@
 
 require "pathname"
 require "yaml"
+require_relative "plugin_asset_policy"
 
 module Vizcore
   # Reads a project-level manifest such as vizcore.yml.
@@ -36,6 +37,8 @@ module Vizcore
         feature_file: expand_path(value_at(data, "feature_file") || value_at(data, "features")),
         control_preset: expand_path(value_at(data, "control_preset") || value_at(data, "controlPreset")),
         osc_port: value_at(data, "osc_port") || value_at(data, "sync", "osc_port") || value_at(data, "sync", "osc", "port"),
+        scene_switch_effect: value_at(data, "scene_switch_effect"),
+        scene_switch_effect_duration: value_at(data, "scene_switch_effect_duration"),
         plugin_assets: plugin_assets(profile: profile)
       }.compact
     end
@@ -49,7 +52,8 @@ module Vizcore
     def plugin_assets(profile: nil)
       entries = plugin_entries(profile: profile)
       assets = base_values("plugin_assets", "frontend_plugins") + profile_values(profile, "plugin_assets", "frontend_plugins")
-      (entries.filter_map { |entry| plugin_asset_path(entry) } + assets.filter_map { |entry| expand_path(entry) }).uniq
+      manifest_assets = assets.filter_map { |entry| validate_plugin_asset_path(expand_path(entry)) }
+      (entries.filter_map { |entry| plugin_asset_path(entry) } + manifest_assets).uniq
     end
 
     # @return [Array<String>] configured profile names
@@ -124,7 +128,7 @@ module Vizcore
     def plugin_asset_path(entry)
       return nil unless entry.is_a?(Hash)
 
-      expand_path(entry["asset"] || entry[:asset] || entry["frontend"] || entry[:frontend])
+      validate_plugin_asset_path(expand_path(entry["asset"] || entry[:asset] || entry["frontend"] || entry[:frontend]))
     end
 
     def expand_path(value)
@@ -135,6 +139,12 @@ module Vizcore
       path_value.absolute? ? path_value : @root.join(path_value).expand_path
     end
 
+    def validate_plugin_asset_path(path)
+      return nil unless path
+
+      Vizcore::PluginAssetPolicy.validate!(path, root: @root)
+    end
+
     def deep_merge(base, overlay)
       base.merge(overlay) do |_key, left, right|
         left.is_a?(Hash) && right.is_a?(Hash) ? deep_merge(left, right) : right