vizcore 1.0.0 → 1.2.0

data/lib/vizcore/dsl/layer_builder.rb

@@ -2,30 +2,85 @@
 
 require_relative "mapping_transform_builder"
 require_relative "reaction_builder"
+require_relative "../deep_copy"
+require_relative "../layer_catalog"
+require_relative "../shape"
+require_relative "color_helpers"
+require_relative "layout_helpers"
 
 module Vizcore
   module DSL
     # Builder for one render layer in a scene.
     class LayerBuilder
       NO_ARGUMENT = Object.new.freeze
+      SHAPE_SCHEMA_VERSION = 2
       MAPPING_SOURCE_KINDS = %i[
-        amplitude frequency_band fft_spectrum onset kick snare hihat beat beat_confidence beat_pulse beat_count bpm
+        amplitude peak frequency_band frequency_band_peak fft_spectrum onset kick snare hihat beat beat_confidence beat_pulse beat_count bpm
+        beat_phase beat_2 beat_4 beat_8 beat_triplet triplet bar_phase bar_count phrase_count bpm_confidence
+        spectral_centroid spectral_rolloff spectral_flatness spectral_flux zero_crossing_rate global lfo adsr envelope
       ].freeze
+      PATH_DEFAULT_DETAIL = 32
+      PATH_MIN_DETAIL = 4
+      PATH_MAX_DETAIL = 128
+      PATH_DEFAULT_MAX_SEGMENTS = 4096
+      SHAPE_TARGET_ALIASES = {
+        "translate_x" => "transform.translate.x",
+        "translate_y" => "transform.translate.y",
+        "rotate" => "transform.rotate",
+        "rotation" => "transform.rotate",
+        "scale" => "transform.scale",
+        "scale_x" => "transform.scale.x",
+        "scale_y" => "transform.scale.y",
+        "origin_x" => "transform.origin.x",
+        "origin_y" => "transform.origin.y"
+      }.freeze
+      SHAPE_STYLE_KEYS = Vizcore::Shape::STYLE_KEYS
+      SHAPE_TRANSFORM_KEYS = %i[translate rotate rotation scale origin].freeze
+      STRICT_PARAM_ALLOWLIST = %i[
+        custom_shape_controls custom_shapes glsl_source group origin rotate scale translate
+      ].freeze
+
+      # Reference to an already declared shape, used by `map ... to: shape(:id).radius`.
+      class ShapeReference
+        def initialize(prefix)
+          @prefix = prefix
+        end
+
+        def method_missing(method_name, *args, &block)
+          return super unless args.empty? && block.nil?
+
+          target = SHAPE_TARGET_ALIASES.fetch(method_name.to_s, method_name.to_s)
+          :"#{@prefix}.#{target}"
+        end
+
+        def respond_to_missing?(_method_name, _include_private = false)
+          true
+        end
+      end
 
       # @param name [Symbol, String] layer identifier
       # @param styles [Hash] reusable layer parameter styles
       # @param defaults [Hash] default params applied before layer-specific values
-      def initialize(name:, styles: {}, defaults: {})
+      # @param strict [Boolean] true when unknown layer params should fail
+      # @param mapping_presets [Hash] reusable mapping presets
+      def initialize(name:, styles: {}, defaults: {}, mapping_presets: {}, strict: false)
         @name = name.to_sym
         @styles = styles
+        @mapping_presets = mapping_presets
+        @strict = !!strict
         @type = nil
         @shader = nil
         @glsl = nil
         @params = deep_dup(defaults)
         @param_schema = {}
         @mappings = []
+        @shape_index_by_id = {}
+        @shape_group_stack = [{}]
       end
 
+      include ColorHelpers
+      include LayoutHelpers
+
       # Evaluate a layer block.
       #
       # @yield Layer DSL methods
@@ -72,8 +127,8 @@ module Vizcore
       # @param options [Hash] shape params such as `count`, `radius`, `x`, and `y`
       # @yield optional block evaluated in the shape context
       # @return [Hash]
-      def circle(**options, &block)
-        build_shape(:circle, options, &block)
+      def circle(id = nil, **options, &block)
+        build_shape(:circle, shape_options(id, options), &block)
       end
 
       # Declare a 2D line primitive for a shape layer.
@@ -81,8 +136,133 @@ module Vizcore
       # @param options [Hash] shape params such as `x1`, `y1`, `x2`, and `y2`
       # @yield optional block evaluated in the shape context
       # @return [Hash]
-      def line(**options, &block)
-        build_shape(:line, options, &block)
+      def line(id = nil, **options, &block)
+        build_shape(:line, shape_options(id, options), &block)
+      end
+
+      # Declare a 2D rectangle primitive for a shape layer.
+      #
+      # @param id [Symbol, String, nil] optional shape identifier
+      # @param options [Hash] shape params such as `x`, `y`, `width`, `height`, and `radius`
+      # @yield optional block evaluated in the shape context
+      # @return [Hash]
+      def rect(id = nil, **options, &block)
+        build_shape(:rect, shape_options(id, options), schema_version: true, &block)
+      end
+
+      # Declare a closed polygon primitive for a shape layer.
+      #
+      # @param id [Symbol, String, nil] optional shape identifier
+      # @param options [Hash] shape params including `points`
+      # @yield optional block evaluated in the shape context
+      # @return [Hash]
+      def polygon(id = nil, **options, &block)
+        build_shape(:polygon, shape_options(id, options), schema_version: true, &block)
+      end
+
+      # Declare an open polyline primitive for a shape layer.
+      #
+      # @param id [Symbol, String, nil] optional shape identifier
+      # @param options [Hash] shape params including `points`
+      # @yield optional block evaluated in the shape context
+      # @return [Hash]
+      def polyline(id = nil, **options, &block)
+        build_shape(:polyline, shape_options(id, options).merge(closed: false), schema_version: true, &block)
+      end
+
+      # Declare a path primitive using SVG-like path commands.
+      #
+      # @param id [Symbol, String, nil] optional shape identifier
+      # @param options [Hash] path params such as `detail`
+      # @yield block containing path commands and shape styling
+      # @return [Hash]
+      def path(id = nil, **options, &block)
+        shape = shape_options(id, options)
+        shape[:commands] ||= []
+        build_shape(:path, shape, schema_version: true, &block)
+      end
+
+      # Declare a quadratic or cubic bezier curve. The serialized primitive is a path.
+      #
+      # @param id [Symbol, String, nil] optional shape identifier
+      # @param from [Array<Numeric>] start point
+      # @param to [Array<Numeric>] end point
+      # @param control [Array<Numeric>, nil] quadratic control point
+      # @param c1 [Array<Numeric>, nil] first cubic control point
+      # @param c2 [Array<Numeric>, nil] second cubic control point
+      # @param options [Hash] additional path params
+      # @yield optional block evaluated in the shape context
+      # @return [Hash]
+      def bezier(id = nil, from:, to:, control: nil, c1: nil, c2: nil, **options, &block)
+        commands = [["M", *point_values(from)]]
+        if control
+          commands << ["Q", *point_values(control), *point_values(to)]
+        elsif c1 && c2
+          commands << ["C", *point_values(c1), *point_values(c2), *point_values(to)]
+        else
+          raise ArgumentError, "bezier requires either :control or both :c1 and :c2"
+        end
+
+        build_shape(:path, shape_options(id, options).merge(commands: commands), schema_version: true, &block)
+      end
+
+      # Declare a star polygon primitive for a shape layer.
+      #
+      # @param id [Symbol, String, nil] optional shape identifier
+      # @param options [Hash] shape params such as `points`, `radius`, and `inner_radius`
+      # @yield optional block evaluated in the shape context
+      # @return [Hash]
+      def star(id = nil, **options, &block)
+        build_shape(:star, shape_options(id, options), schema_version: true, &block)
+      end
+
+      # Expand a registered Ruby custom shape into normal shape primitives.
+      #
+      # @param renderer [Symbol, String, Class, Module, #call] registered shape name or renderer
+      # @param options [Hash] custom shape params
+      # @yield optional block applied to each generated primitive
+      # @return [Array<Hash>]
+      def custom_shape(renderer, **options, &block)
+        mark_shape_schema_version!
+        shape_id = options.delete(:id)
+        dynamic = options.delete(:dynamic)
+        static = options.delete(:static)
+        raise ArgumentError, "custom_shape cannot be both static and dynamic" if dynamic && static
+
+        dynamic = true if static == false
+        return append_dynamic_custom_shape(renderer, options, shape_id: shape_id, &block) if dynamic
+
+        primitives = expand_custom_shape(renderer, options, shape_id: shape_id, cache: !!static)
+        raise ArgumentError, "custom_shape produced no primitives" if primitives.empty?
+        raise ArgumentError, "custom_shape id can only be assigned when one primitive is produced" if shape_id && primitives.length > 1
+
+        @type ||= :shape
+        @params[:shapes] ||= []
+        primitives.map do |primitive|
+          primitive[:id] ||= shape_id.to_sym if shape_id
+          append_expanded_shape(primitive, &block)
+        end
+      end
+
+      # Apply shared style and transform to shape primitives declared in the block.
+      #
+      # Group attributes are flattened into child primitives so the frontend only
+      # needs to render regular shape primitives.
+      #
+      # @param id [Symbol, String, nil] optional group identifier, currently documentation-only
+      # @param attrs [Hash] initial group style/transform attrs
+      # @yield shape declarations
+      # @return [Array<Hash>]
+      def group(_id = nil, **attrs, &block)
+        raise ArgumentError, "group requires a block" unless block
+
+        mark_shape_schema_version!
+        @type ||= :shape
+        @shape_group_stack << merge_shape_group(current_shape_group, normalize_shape_group(attrs))
+        instance_eval(&block)
+        @params[:shapes] || []
+      ensure
+        @shape_group_stack.pop if @shape_group_stack.length > 1
       end
 
       # Group shape primitives in a block for readability.
@@ -146,6 +326,22 @@ module Vizcore
       # @param value [String] text fill color
       # @return [String]
       def fill(value)
+        if @current_shape
+          @current_shape[:fill] = value.to_s
+          mark_shape_schema_version!
+          return @current_shape
+        end
+
+        if @current_custom_shape
+          current_custom_shape_style[:fill] = value.to_s
+          return @current_custom_shape
+        end
+
+        if in_shape_group?
+          current_shape_group[:fill] = value.to_s
+          return current_shape_group
+        end
+
         @params[:color] = value.to_s
       end
 
@@ -160,6 +356,20 @@ module Vizcore
           return @current_shape
         end
 
+        if @current_custom_shape
+          current_custom_shape_style[:stroke] = normalize_non_negative_param_number(value, :stroke) unless value.equal?(NO_ARGUMENT)
+          current_custom_shape_style[:stroke_width] = normalize_non_negative_param_number(width, :stroke_width) unless width.nil?
+          current_custom_shape_style[:stroke_color] = color.to_s unless color.nil?
+          return @current_custom_shape
+        end
+
+        if in_shape_group?
+          current_shape_group[:stroke] = normalize_non_negative_param_number(value, :stroke) unless value.equal?(NO_ARGUMENT)
+          current_shape_group[:stroke_width] = normalize_non_negative_param_number(width, :stroke_width) unless width.nil?
+          current_shape_group[:stroke_color] = color.to_s unless color.nil?
+          return current_shape_group
+        end
+
         @params[:stroke_width] = normalize_non_negative_param_number(width, :stroke_width) unless width.nil?
         @params[:stroke_color] = color.to_s unless color.nil?
         @params
@@ -177,9 +387,198 @@ module Vizcore
       # @param value [Symbol, String] layer compositing mode
       # @return [Symbol]
       def blend(value)
+        if @current_shape
+          @current_shape[:blend] = value.to_sym
+          mark_shape_schema_version!
+          return @current_shape
+        end
+
+        if @current_custom_shape
+          current_custom_shape_style[:blend] = value.to_sym
+          return @current_custom_shape
+        end
+
+        if in_shape_group?
+          current_shape_group[:blend] = value.to_sym
+          return current_shape_group
+        end
+
         @params[:blend] = value.to_sym
       end
 
+      # Set layer or shape opacity.
+      #
+      # @param value [Numeric]
+      # @return [Float, Hash]
+      def opacity(value)
+        if @current_shape
+          @current_shape[:opacity] = normalize_param_number(value, :opacity)
+          mark_shape_schema_version!
+          return @current_shape
+        end
+
+        if @current_custom_shape
+          current_custom_shape_style[:opacity] = normalize_param_number(value, :opacity)
+          return @current_custom_shape
+        end
+
+        if in_shape_group?
+          current_shape_group[:opacity] = current_shape_group.key?(:opacity) ? normalize_param_number(current_shape_group[:opacity], :opacity) * normalize_param_number(value, :opacity) : normalize_param_number(value, :opacity)
+          return current_shape_group
+        end
+
+        @params[:opacity] = normalize_param_number(value, :opacity)
+      end
+
+      # Set a shape/layer translation transform.
+      #
+      # @param args [Array<Numeric>]
+      # @param x [Numeric, nil]
+      # @param y [Numeric, nil]
+      # @return [Hash]
+      def translate(*args, x: nil, y: nil)
+        values = normalize_xy_args(args, x: x, y: y, name: :translate)
+        if @current_shape
+          current_shape_transform[:translate] = values
+          return @current_shape
+        end
+
+        if @current_custom_shape
+          current_custom_shape_transform[:translate] = add_shape_xy(current_custom_shape_transform[:translate], values)
+          return @current_custom_shape
+        end
+
+        if in_shape_group?
+          current_shape_group_transform[:translate] = add_shape_xy(current_shape_group_transform[:translate], values)
+          return current_shape_group
+        end
+
+        @params[:translate] = values
+      end
+
+      # Set a shape/layer rotation transform in degrees.
+      #
+      # @param value [Numeric]
+      # @return [Float, Hash]
+      def rotate(value)
+        rotation = normalize_param_number(value, :rotate)
+        if @current_shape
+          current_shape_transform[:rotate] = rotation
+          return @current_shape
+        end
+
+        if @current_custom_shape
+          current_custom_shape_transform[:rotate] = normalize_param_number(current_custom_shape_transform[:rotate] || 0, :rotate) + rotation
+          return @current_custom_shape
+        end
+
+        if in_shape_group?
+          current_shape_group_transform[:rotate] = normalize_param_number(current_shape_group_transform[:rotate] || 0, :rotate) + rotation
+          return current_shape_group
+        end
+
+        @params[:rotate] = rotation
+      end
+
+      # Set a shape/layer scale transform.
+      #
+      # @param value [Numeric]
+      # @param x [Numeric, nil]
+      # @param y [Numeric, nil]
+      # @return [Float, Hash]
+      def scale(value = NO_ARGUMENT, x: nil, y: nil)
+        scale_value = normalize_scale_args(value, x: x, y: y)
+        if @current_shape
+          current_shape_transform[:scale] = scale_value
+          return @current_shape
+        end
+
+        if @current_custom_shape
+          current_custom_shape_transform[:scale] = multiply_shape_scale(current_custom_shape_transform[:scale], scale_value)
+          return @current_custom_shape
+        end
+
+        if in_shape_group?
+          current_shape_group_transform[:scale] = multiply_shape_scale(current_shape_group_transform[:scale], scale_value)
+          return current_shape_group
+        end
+
+        @params[:scale] = scale_value
+      end
+
+      # Set a shape/layer transform origin.
+      #
+      # @param args [Array<Numeric>]
+      # @param x [Numeric, nil]
+      # @param y [Numeric, nil]
+      # @return [Hash]
+      def origin(*args, x: nil, y: nil)
+        values = normalize_xy_args(args, x: x, y: y, name: :origin)
+        if @current_shape
+          current_shape_transform[:origin] = values
+          return @current_shape
+        end
+
+        if @current_custom_shape
+          current_custom_shape_transform[:origin] = values
+          return @current_custom_shape
+        end
+
+        if in_shape_group?
+          current_shape_group_transform[:origin] = values
+          return current_shape_group
+        end
+
+        @params[:origin] = values
+      end
+
+      # Return a reference object for mapping to a named shape.
+      #
+      # @param id [Symbol, String]
+      # @return [ShapeReference]
+      def shape(id)
+        key = id.to_sym
+        index = @shape_index_by_id.fetch(key) do
+          suggestion_message = shape_id_suggestions(key)
+          message = "unknown shape id: #{key.inspect}"
+          message = "#{message}. Did you mean: #{suggestion_message}" unless suggestion_message.empty?
+          raise ArgumentError, message
+        end
+        ShapeReference.new("shapes.#{index}")
+      end
+
+      def move_to(x, y)
+        append_path_command("M", x, y)
+      end
+
+      def line_to(x, y)
+        append_path_command("L", x, y)
+      end
+
+      def quad_to(cx, cy, x, y)
+        append_path_command("Q", cx, cy, x, y)
+      end
+
+      def cubic_to(c1x, c1y, c2x, c2y, x, y)
+        append_path_command("C", c1x, c1y, c2x, c2y, x, y)
+      end
+
+      def horizontal_to(x)
+        append_path_command("H", x)
+      end
+
+      def vertical_to(y)
+        append_path_command("V", y)
+      end
+
+      def arc_to(rx, ry, rotation, large_arc, sweep, x, y)
+        append_path_command("A", rx, ry, rotation, large_arc, sweep, x, y)
+      end
+
+      def close
+        append_path_command("Z")
+      end
+
       # Store an ordered color palette for this layer.
       #
       # @param colors [Array<String, Array<String>>] color values such as "#00ffff"
@@ -189,6 +588,17 @@ module Vizcore
         @params[:palette] = normalize_palette(colors)
       end
 
+      # Append one post effect to this layer's post effect chain.
+      #
+      # @param name [Symbol, String] effect key
+      # @return [Symbol]
+      def post(name)
+        raise ArgumentError, "post expects a symbol or string" unless name
+
+        @params[:post_effects] ||= []
+        @params[:post_effects] << name.to_sym
+      end
+
       # Apply a named style by merging its params into this layer.
       #
       # @param name [Symbol, String] style identifier
@@ -232,6 +642,7 @@ module Vizcore
       # @raise [ArgumentError] when the mapping is empty or invalid
       # @return [void]
       def map(definition = nil, **options, &block)
+        definition, options = normalize_custom_shape_mapping(definition, options) if @custom_shape_target_prefix
         definition, options = normalize_shape_mapping(definition, options) if @shape_target_prefix
 
         if options.key?(:to)
@@ -257,6 +668,17 @@ module Vizcore
         end
       end
 
+      # Apply a named mapping preset to this layer.
+      #
+      # @param name [Symbol, String] mapping preset identifier
+      # @raise [ArgumentError] when the preset is unknown
+      # @return [void]
+      def use_mapping(name)
+        preset_name = name.to_sym
+        preset = @mapping_presets.fetch(preset_name) { raise ArgumentError, "unknown mapping preset: #{preset_name}" }
+        preset.each { |mapping| @mappings << deep_dup(mapping) }
+      end
+
       # High-level mapping DSL for describing audio reactions inside a layer.
       #
       # @param source_value [Hash, Symbol, String] analysis source descriptor
@@ -284,42 +706,82 @@ module Vizcore
         mapping_source(:amplitude)
       end
 
+      # @return [Hash] source descriptor for absolute sample peak level
+      def peak
+        mapping_source(:peak)
+      end
+
       # @param name [Symbol, String] band key (`sub`, `low`, `mid`, `high`)
       # @return [Hash] source descriptor for a frequency band
       def frequency_band(name)
         mapping_source(:frequency_band, band: name.to_sym)
       end
 
+      # @return [Hash] source descriptor for a held frequency-band peak
+      def frequency_band_peak(name)
+        mapping_source(:frequency_band_peak, band: name.to_sym)
+      end
+
       # @return [Hash] source descriptor for the sub-bass frequency band
       def sub
         frequency_band(:sub)
       end
 
+      # @return [Hash] source descriptor for the held sub-bass peak
+      def sub_peak
+        frequency_band_peak(:sub)
+      end
+
       # @return [Hash] source descriptor for the low/bass frequency band
       def low
         frequency_band(:low)
       end
 
+      # @return [Hash] source descriptor for the held low/bass peak
+      def low_peak
+        frequency_band_peak(:low)
+      end
+
       # @return [Hash] source descriptor for the low/bass frequency band
       def bass
         frequency_band(:low)
       end
 
+      # @return [Hash] source descriptor for the held low/bass peak
+      def bass_peak
+        frequency_band_peak(:low)
+      end
+
       # @return [Hash] source descriptor for the mid frequency band
       def mid
         frequency_band(:mid)
       end
 
+      # @return [Hash] source descriptor for the held mid peak
+      def mid_peak
+        frequency_band_peak(:mid)
+      end
+
       # @return [Hash] source descriptor for the high frequency band
       def high
         frequency_band(:high)
       end
 
+      # @return [Hash] source descriptor for the held high peak
+      def high_peak
+        frequency_band_peak(:high)
+      end
+
       # @return [Hash] source descriptor for the high/treble frequency band
       def treble
         frequency_band(:high)
       end
 
+      # @return [Hash] source descriptor for the held high/treble peak
+      def treble_peak
+        frequency_band_peak(:high)
+      end
+
       # @return [Hash] source descriptor for FFT spectrum array
       def fft_spectrum
         mapping_source(:fft_spectrum)
@@ -378,13 +840,138 @@ module Vizcore
         mapping_source(:beat_count)
       end
 
+      # @return [Hash] source descriptor for 0.0..1.0 phase within the current beat
+      def beat_phase
+        mapping_source(:beat_phase)
+      end
+
+      # @return [Hash] source descriptor for half-beat subdivision pulses
+      def beat_2
+        mapping_source(:beat_2)
+      end
+
+      # @return [Hash] source descriptor for quarter-beat subdivision pulses
+      def beat_4
+        mapping_source(:beat_4)
+      end
+
+      # @return [Hash] source descriptor for eighth-beat subdivision pulses
+      def beat_8
+        mapping_source(:beat_8)
+      end
+
+      # @return [Hash] source descriptor for triplet subdivision pulses
+      def beat_triplet
+        mapping_source(:beat_triplet)
+      end
+
+      # @return [Hash] source descriptor for triplet subdivision pulses
+      def triplet
+        mapping_source(:beat_triplet)
+      end
+
+      # @return [Hash] source descriptor for 0.0..1.0 phase within the current 4-beat bar
+      def bar_phase
+        mapping_source(:bar_phase)
+      end
+
+      # @return [Hash] source descriptor for completed 4-beat bars
+      def bar_count(value = NO_ARGUMENT)
+        return @params[:bar_count] = Integer(value) unless value.equal?(NO_ARGUMENT)
+
+        mapping_source(:bar_count)
+      end
+
+      # @return [Hash] source descriptor for completed 8-bar phrases
+      def phrase_count
+        mapping_source(:phrase_count)
+      end
+
       # @return [Hash] source descriptor for estimated BPM
       def bpm
         mapping_source(:bpm)
       end
 
+      # @return [Hash] source descriptor for tempo estimator confidence
+      def bpm_confidence
+        mapping_source(:bpm_confidence)
+      end
+
+      # @return [Hash] source descriptor for spectral centroid in Hz
+      def spectral_centroid
+        mapping_source(:spectral_centroid)
+      end
+
+      # @return [Hash] source descriptor for spectral rolloff in Hz
+      def spectral_rolloff
+        mapping_source(:spectral_rolloff)
+      end
+
+      # @return [Hash] source descriptor for spectral flatness
+      def spectral_flatness
+        mapping_source(:spectral_flatness)
+      end
+
+      # @return [Hash] source descriptor for positive spectrum delta
+      def spectral_flux
+        mapping_source(:spectral_flux)
+      end
+
+      # @return [Hash] source descriptor for time-domain zero crossing rate
+      def zero_crossing_rate
+        mapping_source(:zero_crossing_rate)
+      end
+
+      # @param name [Symbol, String] runtime global value name
+      # @return [Hash] source descriptor for mutable runtime globals
+      def global(name)
+        mapping_source(:global, name: name.to_sym)
+      end
+
+      # @param wave [Symbol, String] one of `sine`, `triangle`, `saw`, `square`
+      # @param rate [Numeric] cycles per second
+      # @param phase [Numeric] phase offset in cycles
+      # @return [Hash] source descriptor for a time-based low-frequency oscillator
+      def lfo(wave = :sine, rate: 1.0, phase: 0.0)
+        mapping_source(:lfo, wave: wave.to_sym, rate: Float(rate), phase: Float(phase))
+      rescue ArgumentError, TypeError
+        raise ArgumentError, "lfo rate and phase must be numeric"
+      end
+
+      # @param source [Symbol, Hash] source to trigger the envelope
+      # @param attack [Numeric] seconds from 0.0 to peak
+      # @param decay [Numeric] seconds from peak to sustain
+      # @param sustain [Numeric] sustain gain once decay is complete (0.0..1.0)
+      # @param release [Numeric] seconds from sustain to 0.0
+      # @param threshold [Numeric] value threshold that starts attack
+      # @param peak [Numeric] peak gain multiplier
+      # @return [Hash] source descriptor for an ADSR envelope
+      def adsr(source = :kick, attack: 0.02, decay: 0.08, sustain: 0.7, release: 0.16, threshold: 0.0, peak: 1.0)
+        source_value = source.nil? ? { kind: :kick } : normalize_source(source)
+        mapping_source(
+          :adsr,
+          source: source_value,
+          attack: normalize_non_negative_float(attack, :attack),
+          decay: normalize_non_negative_float(decay, :decay),
+          sustain: clamp(normalize_float(sustain, :sustain), 0.0, 1.0),
+          release: normalize_non_negative_float(release, :release),
+          threshold: normalize_float(threshold, :threshold),
+          peak: normalize_float(peak, :peak)
+        )
+      end
+
+      # Alias for ADSR envelope mapping source.
+      #
+      # @param source [Symbol, Hash] source to trigger the envelope
+      # @param options [Numeric] envelope timing and shaping values
+      # @return [Hash] source descriptor for a general envelope
+      def envelope(source = :kick, **options)
+        adsr(source, **options)
+      end
+
       # @return [Hash] serialized layer payload
       def to_h
+        validate_strict_params! if @strict
         layer = {
           name: @name,
           type: resolved_type,
@@ -405,6 +992,16 @@ module Vizcore
           return args.first
         end
 
+        if @current_custom_shape && block.nil? && args.length == 1
+          @current_custom_shape[:params][method_name.to_sym] = args.first
+          return args.first
+        end
+
+        if in_shape_group? && block.nil? && args.length == 1
+          current_shape_group[method_name.to_sym] = args.first
+          return args.first
+        end
+
         if block.nil? && args.length == 1
           @params[method_name.to_sym] = args.first
           return args.first
@@ -414,25 +1011,77 @@ module Vizcore
       end
 
       def respond_to_missing?(method_name, include_private = false)
-        @params.key?(method_name.to_sym) || super
+        !!@current_custom_shape || @params.key?(method_name.to_sym) || super
       end
 
       private
 
-      def build_shape(kind, options, &block)
+      def build_shape(kind, options, schema_version: false, &block)
         @type ||= :shape
+        mark_shape_schema_version! if schema_version
         shape = normalize_shape(kind, options)
         @params[:shapes] ||= []
         shape_index = @params[:shapes].length
+        register_shape_id!(shape, shape_index)
         @params[:shapes] << shape
 
         with_shape_context(shape, shape_index) do
           instance_eval(&block) if block
         end
+        apply_current_shape_group!(shape)
+        validate_shape!(shape)
 
         shape
       end
 
+      def append_expanded_shape(shape, &block)
+        shape_index = @params[:shapes].length
+        register_shape_id!(shape, shape_index)
+        @params[:shapes] << shape
+
+        with_shape_context(shape, shape_index) do
+          instance_eval(&block) if block
+        end
+        apply_current_shape_group!(shape)
+        validate_shape!(shape)
+
+        shape
+      end
+
+      def append_dynamic_custom_shape(renderer, options, shape_id:, &block)
+        definition = custom_shape_definition(renderer)
+        @type ||= :shape
+        @params[:custom_shapes] ||= []
+        descriptor = {
+          name: definition.name || renderer,
+          renderer: definition.renderer,
+          params: deep_dup(options),
+          style: {},
+          transform: {},
+          dynamic: true
+        }
+        param_schema = custom_shape_param_schema(definition.renderer)
+        descriptor[:param_schema] = param_schema unless param_schema.empty?
+        descriptor[:shape_id] = shape_id.to_sym if shape_id
+        descriptor_index = @params[:custom_shapes].length
+        @params[:custom_shapes] << descriptor
+
+        with_custom_shape_context(descriptor, descriptor_index) do
+          instance_eval(&block) if block
+        end
+        apply_current_shape_group_to_custom_shape!(descriptor)
+
+        descriptor
+      end
+
+      def shape_options(id, options)
+        return options if id.nil?
+
+        raise ArgumentError, "shape id specified twice" if options.key?(:id)
+
+        options.merge(id: id.to_sym)
+      end
+
       def normalize_shape(kind, options)
         shape = { kind: kind.to_sym }
         options.each do |key, value|
@@ -441,6 +1090,307 @@ module Vizcore
         shape
       end
 
+      def normalize_shape_group(attrs)
+        attrs.each_with_object({}) do |(key, value), group|
+          symbol_key = key.to_sym
+          if SHAPE_TRANSFORM_KEYS.include?(symbol_key)
+            transform_key = symbol_key == :rotation ? :rotate : symbol_key
+            group[:transform] ||= {}
+            group[:transform][transform_key] = value
+          else
+            group[symbol_key] = value
+          end
+        end
+      end
+
+      def merge_shape_group(parent, child)
+        output = deep_dup(parent)
+        child.each do |key, value|
+          if key == :transform
+            output[:transform] = compose_shape_transform(output[:transform], value)
+          elsif key == :opacity && output.key?(:opacity)
+            output[:opacity] = normalize_param_number(output[:opacity], :opacity) * normalize_param_number(value, :opacity)
+          else
+            output[key] = deep_dup(value)
+          end
+        end
+        output
+      end
+
+      def apply_current_shape_group!(shape)
+        group = current_shape_group
+        return shape if group.empty?
+
+        SHAPE_STYLE_KEYS.each do |key|
+          next unless group.key?(key)
+
+          if key == :opacity && shape.key?(:opacity)
+            shape[:opacity] = normalize_param_number(group[:opacity], :opacity) * normalize_param_number(shape[:opacity], :opacity)
+          else
+            shape[key] = deep_dup(group[key]) unless shape.key?(key)
+          end
+        end
+        shape[:transform] = compose_shape_transform(group[:transform], shape[:transform]) if group[:transform]
+        shape
+      end
+
+      def apply_current_shape_group_to_custom_shape!(descriptor)
+        group = current_shape_group
+        return descriptor if group.empty?
+
+        style = descriptor[:style] ||= {}
+        SHAPE_STYLE_KEYS.each do |key|
+          next unless group.key?(key)
+
+          if key == :opacity && style.key?(:opacity)
+            style[:opacity] = normalize_param_number(group[:opacity], :opacity) * normalize_param_number(style[:opacity], :opacity)
+          else
+            style[key] = deep_dup(group[key]) unless style.key?(key)
+          end
+        end
+        descriptor[:transform] = compose_shape_transform(group[:transform], descriptor[:transform]) if group[:transform]
+        descriptor
+      end
+
+      def compose_shape_transform(parent, child)
+        return deep_dup(child || {}) unless parent
+
+        child ||= {}
+        output = deep_dup(parent)
+        output[:translate] = add_shape_xy(parent[:translate], child[:translate]) if child.key?(:translate)
+        output[:origin] = child[:origin] if child.key?(:origin)
+        output[:rotate] = normalize_param_number(parent[:rotate] || 0, :rotate) + normalize_param_number(child[:rotate] || 0, :rotate) if child.key?(:rotate)
+        output[:scale] = multiply_shape_scale(parent[:scale], child[:scale]) if child.key?(:scale)
+        output
+      end
+
+      def add_shape_xy(parent, child)
+        parent ||= {}
+        child ||= {}
+        {
+          x: normalize_param_number(parent[:x] || parent["x"] || 0, :"translate.x") + normalize_param_number(child[:x] || child["x"] || 0, :"translate.x"),
+          y: normalize_param_number(parent[:y] || parent["y"] || 0, :"translate.y") + normalize_param_number(child[:y] || child["y"] || 0, :"translate.y")
+        }
+      end
+
+      def multiply_shape_scale(parent, child)
+        parent = shape_scale_pair(parent)
+        child = shape_scale_pair(child)
+        { x: parent[:x] * child[:x], y: parent[:y] * child[:y] }
+      end
+
+      def shape_scale_pair(value)
+        return { x: normalize_param_number(value[:x] || value["x"] || 1, :"scale.x"), y: normalize_param_number(value[:y] || value["y"] || 1, :"scale.y") } if value.is_a?(Hash)
+
+        scale = normalize_param_number(value || 1, :scale)
+        { x: scale, y: scale }
+      end
+
+      def current_shape_group
+        @shape_group_stack.last
+      end
+
+      def current_shape_group_transform
+        current_shape_group[:transform] ||= {}
+      end
+
+      def current_custom_shape_style
+        @current_custom_shape[:style] ||= {}
+      end
+
+      def current_custom_shape_transform
+        @current_custom_shape[:transform] ||= {}
+      end
+
+      def in_shape_group?
+        @shape_group_stack.length > 1
+      end
+
+      def validate_shape!(shape)
+        validate_non_negative_shape_numbers!(shape)
+        case shape.fetch(:kind)
+        when :polygon
+          validate_shape_points!(shape, minimum: 3)
+        when :polyline
+          validate_shape_points!(shape, minimum: 2)
+        when :path
+          validate_path_shape!(shape)
+        end
+      end
+
+      def validate_path_shape!(shape)
+        commands = Array(shape[:commands])
+        raise ArgumentError, "Invalid path#{shape_label(shape)}: commands must not be empty" if commands.empty?
+
+        detail = normalized_path_integer(shape, :detail, PATH_DEFAULT_DETAIL).clamp(PATH_MIN_DETAIL, PATH_MAX_DETAIL)
+        max_segments = normalized_path_integer(shape, :max_segments, PATH_DEFAULT_MAX_SEGMENTS)
+        validate_path_tolerance!(shape)
+
+        segment_count = estimated_path_segments(commands, detail)
+        return if segment_count <= max_segments
+
+        raise ArgumentError,
+              "Invalid path#{shape_label(shape)}: max_segments exceeded (#{segment_count} > #{max_segments})"
+      end
+
+      def normalized_path_integer(shape, key, default)
+        value = shape.key?(key) ? shape[key] : default
+        numeric = Integer(value)
+        raise ArgumentError if numeric <= 0
+
+        numeric
+      rescue ArgumentError, TypeError
+        raise ArgumentError, "Invalid path#{shape_label(shape)}: #{key} must be a positive integer"
+      end
+
+      def validate_path_tolerance!(shape)
+        return unless shape.key?(:tolerance)
+
+        value = normalize_param_number(shape[:tolerance], :tolerance)
+        return unless value.negative?
+
+        raise ArgumentError, "Invalid path#{shape_label(shape)}: tolerance must be non-negative"
+      end
+
+      def estimated_path_segments(commands, detail)
+        current = false
+        subpath_start = false
+        commands.sum do |entry|
+          command, *values = Array(entry)
+          case command.to_s.upcase
+          when "M"
+            current = values.length >= 2
+            subpath_start = current
+            0
+          when "L"
+            current && values.length >= 2 ? 1 : 0
+          when "H", "V"
+            current && values.length >= 1 ? 1 : 0
+          when "Q"
+            current && values.length >= 4 ? detail : 0
+          when "C"
+            current && values.length >= 6 ? detail : 0
+          when "A"
+            current && values.length >= 7 ? detail : 0
+          when "Z"
+            current && subpath_start ? 1 : 0
+          else
+            0
+          end
+        end
+      end
+
+      def validate_non_negative_shape_numbers!(shape)
+        %i[radius width height stroke_width inner_radius].each do |key|
+          next unless shape.key?(key)
+
+          value = normalize_param_number(shape[key], key)
+          raise ArgumentError, "Invalid #{shape.fetch(:kind)}#{shape_label(shape)}: #{key} must be non-negative" if value.negative?
+        end
+      end
+
+      def validate_shape_points!(shape, minimum:)
+        points = Array(shape[:points])
+        valid_points = points.count { |point| Array(point).length >= 2 }
+        return if valid_points >= minimum
+
+        raise ArgumentError, "Invalid #{shape.fetch(:kind)}#{shape_label(shape)}: points must contain at least #{minimum} points"
+      end
+
+      def shape_label(shape)
+        shape[:id] ? " `#{shape[:id]}`" : ""
+      end
+
+      def expand_custom_shape(renderer, options, shape_id:, cache: false)
+        definition = custom_shape_definition(renderer)
+        Vizcore::Shape.expand_custom_shape(
+          definition.renderer,
+          params: options,
+          shape_id: shape_id,
+          layer_name: @name,
+          palette: Array(@params[:palette]),
+          shape_name: definition.name || renderer,
+          cache: cache
+        )
+      end
+
+      def custom_shape_definition(renderer)
+        return Vizcore::Shape::Definition.new(name: nil, renderer: renderer) unless renderer.is_a?(Symbol) || renderer.is_a?(String)
+
+        Vizcore.resolve_shape(renderer) || raise(ArgumentError, "Unknown custom shape: #{renderer.inspect}. Register it with `Vizcore.register_shape #{renderer.inspect}, ShapeClass`.")
+      end
+
+      def custom_shape_param_schema(renderer)
+        return [] unless renderer.respond_to?(:shape_param_schema)
+
+        renderer.shape_param_schema.values.map(&:dup)
+      end
+
+      def register_shape_id!(shape, shape_index)
+        id = shape[:id]
+        return if id.nil?
+
+        key = id.to_sym
+        raise ArgumentError, "duplicate shape id: #{key.inspect}" if @shape_index_by_id.key?(key)
+
+        @shape_index_by_id[key] = shape_index
+      end
+
+      def current_shape_transform
+        mark_shape_schema_version!
+        @current_shape[:transform] ||= {}
+      end
+
+      def mark_shape_schema_version!
+        @params[:shape_schema_version] ||= SHAPE_SCHEMA_VERSION
+      end
+
+      def normalize_xy_args(args, x:, y:, name:)
+        if args.length == 2
+          return { x: normalize_param_number(args[0], :"#{name}.x"), y: normalize_param_number(args[1], :"#{name}.y") }
+        end
+
+        if args.length == 1 && args.first.is_a?(Hash)
+          values = args.first
+          x = values.fetch(:x, values["x"])
+          y = values.fetch(:y, values["y"])
+        elsif args.any?
+          raise ArgumentError, "#{name} expects x/y keywords or two numeric arguments"
+        end
+
+        {
+          x: normalize_param_number(x || 0, :"#{name}.x"),
+          y: normalize_param_number(y || 0, :"#{name}.y")
+        }
+      end
+
+      def normalize_scale_args(value, x:, y:)
+        if value.equal?(NO_ARGUMENT)
+          return {
+            x: normalize_param_number(x || 1, :"scale.x"),
+            y: normalize_param_number(y || 1, :"scale.y")
+          }
+        end
+
+        raise ArgumentError, "scale accepts either a value or x/y keywords" unless x.nil? && y.nil?
+
+        normalize_param_number(value, :scale)
+      end
+
+      def append_path_command(command, *values)
+        raise ArgumentError, "#{command} is only available inside a path shape" unless @current_shape&.fetch(:kind) == :path
+
+        @current_shape[:commands] ||= []
+        @current_shape[:commands] << [command, *values]
+      end
+
+      def point_values(value)
+        values = Array(value)
+        raise ArgumentError, "point must contain x and y" unless values.length == 2
+
+        values
+      end
+
       def with_shape_context(shape, shape_index)
         previous_shape = @current_shape
         previous_prefix = @shape_target_prefix
@@ -452,6 +1402,50 @@ module Vizcore
         @shape_target_prefix = previous_prefix
       end
 
+      def with_custom_shape_context(descriptor, descriptor_index)
+        previous_custom_shape = @current_custom_shape
+        previous_prefix = @custom_shape_target_prefix
+        @current_custom_shape = descriptor
+        @custom_shape_target_prefix = "custom_shapes.#{descriptor_index}"
+        yield
+      ensure
+        @current_custom_shape = previous_custom_shape
+        @custom_shape_target_prefix = previous_prefix
+      end
+
+      def normalize_custom_shape_mapping(definition, options)
+        if options.key?(:to)
+          prefixed_options = options.dup
+          prefixed_options[:to] = prefixed_custom_shape_target(prefixed_options[:to])
+          return [definition, prefixed_options]
+        end
+
+        mapping = definition.nil? ? options : Hash(definition)
+        prefixed_mapping = mapping.each_with_object({}) do |(source, target), output|
+          output[source] = prefix_custom_shape_target_value(target)
+        end
+        [prefixed_mapping, {}]
+      end
+
+      def prefix_custom_shape_target_value(target)
+        return prefixed_custom_shape_target(target) unless target.is_a?(Hash)
+
+        target.merge(to: prefixed_custom_shape_target(target.fetch(:to)))
+      rescue KeyError
+        target
+      end
+
+      def prefixed_custom_shape_target(target)
+        target_name = target.to_s
+        return :"#{@custom_shape_target_prefix}.#{target_name}" if target_name.match?(/\A(?:params|style|transform)\./)
+
+        resolved_target = SHAPE_TARGET_ALIASES[target_name]
+        return :"#{@custom_shape_target_prefix}.#{resolved_target}" if resolved_target
+        return :"#{@custom_shape_target_prefix}.style.#{target_name}" if SHAPE_STYLE_KEYS.include?(target_name.to_sym)
+
+        :"#{@custom_shape_target_prefix}.params.#{target_name}"
+      end
+
       def normalize_shape_mapping(definition, options)
         if options.key?(:to)
           prefixed_options = options.dup
@@ -475,7 +1469,9 @@ module Vizcore
       end
 
       def prefixed_shape_target(target)
-        :"#{@shape_target_prefix}.#{target}"
+        target_name = target.to_s
+        resolved_target = SHAPE_TARGET_ALIASES.fetch(target_name, target_name)
+        :"#{@shape_target_prefix}.#{resolved_target}"
       end
 
       def resolved_type
@@ -534,16 +1530,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
 
       def evaluate_transform_block(initial_options, &block)
@@ -577,19 +1564,26 @@ module Vizcore
         raise ArgumentError, "param min must be less than or equal to max"
       end
 
-      def normalize_transform(gain: nil, range: nil, min: nil, max: nil, curve: nil, attack: nil, release: nil, deadzone: nil)
+      def normalize_transform(gain: nil, range: nil, min: nil, max: nil, curve: nil, attack: nil, release: nil, deadzone: nil, threshold: nil, hysteresis: nil, hold: nil, decay: nil, cooldown: nil, one_shot: nil, as: nil)
         range_min, range_max = normalize_range(range, context: "mapping")
         min = range_min if min.nil?
         max = range_max if max.nil?
 
         output = {}
         output[:deadzone] = normalize_non_negative_float(deadzone, :deadzone) unless deadzone.nil?
+        output[:as] = normalize_mapping_mode(as) unless as.nil?
+        output[:threshold] = normalize_float(threshold, :threshold) unless threshold.nil?
+        output[:hysteresis] = normalize_non_negative_float(hysteresis, :hysteresis) unless hysteresis.nil?
         output[:gain] = normalize_float(gain, :gain) unless gain.nil?
         output[:min] = normalize_float(min, :min) unless min.nil?
         output[:max] = normalize_float(max, :max) unless max.nil?
         output[:curve] = normalize_curve(curve) unless curve.nil?
         output[:attack] = clamp(normalize_float(attack, :attack), 0.0, 1.0) unless attack.nil?
         output[:release] = clamp(normalize_float(release, :release), 0.0, 1.0) unless release.nil?
+        output[:hold] = normalize_non_negative_float(hold, :hold) unless hold.nil?
+        output[:decay] = clamp(normalize_float(decay, :decay), 0.0, 1.0) unless decay.nil?
+        output[:cooldown] = normalize_non_negative_float(cooldown, :cooldown) unless cooldown.nil?
+        output[:one_shot] = !!one_shot unless one_shot.nil?
         output
       end
 
@@ -631,11 +1625,30 @@ module Vizcore
 
       def normalize_curve(value)
         curve = value.to_sym
-        return curve if %i[linear sqrt square ease_out].include?(curve)
+        return curve if %i[linear sqrt square ease_out ease_in ease_in_out smoothstep exp log step].include?(curve)
 
         raise ArgumentError, "unsupported mapping curve: #{value.inspect}"
       end
 
+      def normalize_mapping_mode(value)
+        mode = value.to_sym
+        return mode if %i[continuous trigger].include?(mode)
+
+        raise ArgumentError, "unsupported mapping mode: #{value.inspect}"
+      end
+
+      def validate_strict_params!
+        unknown = @params.keys.map(&:to_sym) - strict_allowed_params
+        return if unknown.empty?
+
+        raise ArgumentError, "layer #{@name} has unknown params in strict mode: #{unknown.sort.join(', ')}"
+      end
+
+      def strict_allowed_params
+        catalog_params = Vizcore::LayerCatalog.params_for(resolved_type).keys
+        (catalog_params + @param_schema.keys + STRICT_PARAM_ALLOWLIST).map(&:to_sym).uniq
+      end
+
       def clamp(value, min, max)
         [[value, min].max, max].min
       end
@@ -646,6 +1659,44 @@ module Vizcore
           **options
         }
       end
+
+      def shape_id_suggestions(key)
+        return "" if @shape_index_by_id.empty?
+
+        candidates = @shape_index_by_id.keys
+          .map do |shape_id|
+            [shape_id, levenshtein_distance(shape_id.to_s, key.to_s)]
+          end
+          .select { |_, distance| distance <= 3 }
+          .sort_by { |shape_id, distance| [distance, shape_id.to_s] }
+          .first(3)
+
+        return "" if candidates.empty?
+
+        candidates.map { |shape_id, _| shape_id.inspect }.join(", ")
+      end
+
+      def levenshtein_distance(a, b)
+        prev = (0..b.length).to_a
+        b_chars = b.bytes
+        a_bytes = a.bytes
+
+        a_bytes.each_with_index do |codepoint_a, index_a|
+          current = [index_a + 1]
+          b_chars.each_with_index do |codepoint_b, index_b|
+            cost = codepoint_a == codepoint_b ? 0 : 1
+            current << [
+              current[index_b] + 1,
+              prev[index_b + 1] + 1,
+              prev[index_b] + cost
+            ].min
+          end
+
+          prev = current
+        end
+
+        prev[b.length]
+      end
     end
   end
 end