vizcore 1.0.0 → 1.1.0

data/lib/vizcore/renderer/snapshot_renderer.rb

@@ -8,6 +8,9 @@ module Vizcore
     class SnapshotRenderer
       DEFAULT_WIDTH = 1280
       DEFAULT_HEIGHT = 720
+      PATH_DEFAULT_MAX_SEGMENTS = 4096
+      PATH_HARD_MAX_SEGMENTS = 65_536
+      PATH_MAX_RECURSION = 12
       PALETTE = [
         [56, 189, 248],
         [225, 29, 72],
@@ -156,6 +159,7 @@ module Vizcore
       def render_shape_layer(canvas, layer, audio, color)
         params = Hash(layer[:params] || layer["params"] || {})
         shapes = Array(params[:shapes] || params["shapes"])
+        context = shape_coordinate_context(params)
         pulse = clamp(audio[:beat_pulse])
         alpha = 0.58 + pulse * 0.24
 
@@ -163,34 +167,522 @@ module Vizcore
           shape_hash = Hash(shape)
           case (shape_hash[:kind] || shape_hash["kind"]).to_s
           when "circle"
-            render_circle_shape(canvas, shape_hash, color, alpha)
+            render_circle_shape(canvas, shape_hash, color, alpha, context)
           when "line"
-            render_line_shape(canvas, shape_hash, color, alpha)
+            render_line_shape(canvas, shape_hash, color, alpha, context)
+          when "rect"
+            render_rect_shape(canvas, shape_hash, color, alpha, context)
+          when "polygon", "polyline"
+            render_polygon_shape(canvas, shape_hash, color, alpha, context)
+          when "path"
+            render_path_shape(canvas, shape_hash, color, alpha, context)
+          when "star"
+            render_star_shape(canvas, shape_hash, color, alpha, context)
           end
         end
       rescue ArgumentError, TypeError
         nil
       end
 
-      def render_circle_shape(canvas, shape, color, alpha)
+      def render_circle_shape(canvas, shape, color, alpha, context)
         count = [[Integer(shape[:count] || shape["count"] || 1), 1].max, 32].min
-        radius = Float(shape[:radius] || shape["radius"] || 100).abs
-        x = Float(shape[:x] || shape["x"] || width * 0.5)
-        y = Float(shape[:y] || shape["y"] || height * 0.5)
-        x = width * 0.5 if x.abs <= 1.5
-        y = height * 0.5 if y.abs <= 1.5
+        radius = shape_length(shape[:radius] || shape["radius"] || 100, context, :radius)
+        center = shape_point(shape[:x] || shape["x"] || 0, shape[:y] || shape["y"] || 0, context)
 
         count.times do |index|
-          canvas.draw_circle_outline(x, y, radius * ((index + 1).to_f / count), color, alpha: alpha)
+          ring_radius = radius * ((index + 1).to_f / count)
+          render_polyline_shape(canvas, circle_points(center, ring_radius), shape, color, alpha, context, closed: true)
         end
       end
 
-      def render_line_shape(canvas, shape, color, alpha)
-        x1 = Float(shape[:x1] || shape["x1"] || width * 0.2)
-        y1 = Float(shape[:y1] || shape["y1"] || height * 0.5)
-        x2 = Float(shape[:x2] || shape["x2"] || width * 0.8)
-        y2 = Float(shape[:y2] || shape["y2"] || height * 0.5)
-        canvas.draw_line(x1, y1, x2, y2, color, alpha: alpha)
+      def render_line_shape(canvas, shape, color, alpha, context)
+        defaults = context[:units] == :legacy || context[:units] == :ndc ? [-0.8, 0, 0.8, 0] : [-100, 0, 100, 0]
+        from = shape_point(shape[:x1] || shape["x1"] || defaults[0], shape[:y1] || shape["y1"] || defaults[1], context)
+        to = shape_point(shape[:x2] || shape["x2"] || defaults[2], shape[:y2] || shape["y2"] || defaults[3], context)
+        draw_shape_segment(canvas, from, to, shape, color, alpha, context)
+      end
+
+      def render_rect_shape(canvas, shape, color, alpha, context)
+        center = shape_point(shape[:x] || shape["x"] || 0, shape[:y] || shape["y"] || 0, context)
+        half_width = shape_length(shape[:width] || shape["width"] || 100, context, :x) / 2.0
+        half_height = shape_length(shape[:height] || shape["height"] || 100, context, :y) / 2.0
+        points = [
+          [center[0] - half_width, center[1] - half_height],
+          [center[0] + half_width, center[1] - half_height],
+          [center[0] + half_width, center[1] + half_height],
+          [center[0] - half_width, center[1] + half_height]
+        ]
+        render_polyline_shape(canvas, points, shape, color, alpha, context, closed: true)
+      end
+
+      def render_polygon_shape(canvas, shape, color, alpha, context)
+        points = Array(shape[:points] || shape["points"]).filter_map do |point|
+          values = Array(point)
+          next if values.length < 2
+
+          shape_point(values[0], values[1], context)
+        end
+        closed = (shape[:kind] || shape["kind"]).to_s == "polygon" ? shape.fetch(:closed, shape.fetch("closed", true)) : false
+        render_polyline_shape(canvas, points, shape, color, alpha, context, closed: closed)
+      end
+
+      def render_star_shape(canvas, shape, color, alpha, context)
+        tips = [[Integer(shape[:points] || shape["points"] || 5), 3].max, 128].min
+        center = shape_point(shape[:x] || shape["x"] || 0, shape[:y] || shape["y"] || 0, context)
+        radius = shape_length(shape[:radius] || shape["radius"] || 100, context, :radius)
+        inner_radius = shape_length(shape[:inner_radius] || shape["inner_radius"] || Float(shape[:radius] || shape["radius"] || 100) * 0.5, context, :radius)
+        rotation = Float(shape[:rotation] || shape["rotation"] || -90) * Math::PI / 180.0
+        points = (tips * 2).times.map do |index|
+          angle = rotation + (index.to_f / (tips * 2)) * Math::PI * 2
+          point_radius = index.even? ? radius : inner_radius
+          [center[0] + Math.cos(angle) * point_radius, center[1] - Math.sin(angle) * point_radius]
+        end
+        render_polyline_shape(canvas, points, shape, color, alpha, context, closed: true)
+      end
+
+      def render_path_shape(canvas, shape, color, alpha, context)
+        detail = [[Integer(shape[:detail] || shape["detail"] || 32), 4].max, 128].min
+        tolerance = path_tolerance(shape)
+        segment_budget = { remaining: path_segment_limit(shape) }
+        current = nil
+        subpath_start = nil
+        Array(shape[:commands] || shape["commands"]).each do |entry|
+          command, *values = Array(entry)
+          values = values.map { |value| Float(value) }
+          case command.to_s.upcase
+          when "M"
+            current = values.first(2)
+            subpath_start = current
+          when "L"
+            next unless current && values.length >= 2
+
+            current = draw_raw_path_segment(canvas, current, values.first(2), shape, color, alpha, context, segment_budget)
+          when "H"
+            next unless current && values.length >= 1
+
+            current = draw_raw_path_segment(canvas, current, [values[0], current[1]], shape, color, alpha, context, segment_budget)
+          when "V"
+            next unless current && values.length >= 1
+
+            current = draw_raw_path_segment(canvas, current, [current[0], values[0]], shape, color, alpha, context, segment_budget)
+          when "Q"
+            next unless current && values.length >= 4
+
+            current = draw_quadratic_path(canvas, current, values, detail, tolerance, shape, color, alpha, context, segment_budget)
+          when "C"
+            next unless current && values.length >= 6
+
+            current = draw_cubic_path(canvas, current, values, detail, tolerance, shape, color, alpha, context, segment_budget)
+          when "A"
+            next unless current && values.length >= 7
+
+            current = draw_arc_path(canvas, current, values, detail, shape, color, alpha, context, segment_budget)
+          when "Z"
+            if current && subpath_start
+              current = draw_raw_path_segment(canvas, current, subpath_start, shape, color, alpha, context, segment_budget)
+            end
+          end
+        end
+      end
+
+      def render_polyline_shape(canvas, points, shape, color, alpha, context, closed:)
+        return if points.length < 2
+
+        points.each_cons(2) { |from, to| draw_shape_segment(canvas, from, to, shape, color, alpha, context) }
+        draw_shape_segment(canvas, points.last, points.first, shape, color, alpha, context) if closed && points.length > 2
+      end
+
+      def draw_raw_path_segment(canvas, from, to, shape, color, alpha, context, segment_budget = nil)
+        return to if segment_budget && segment_budget[:remaining] <= 0
+
+        draw_shape_segment(canvas, shape_point(from[0], from[1], context), shape_point(to[0], to[1], context), shape, color, alpha, context)
+        segment_budget[:remaining] -= 1 if segment_budget
+        to
+      end
+
+      def draw_quadratic_path(canvas, current, values, detail, tolerance, shape, color, alpha, context, segment_budget = nil)
+        previous = current
+        control = values.first(2)
+        endpoint = values.last(2)
+        if tolerance
+          draw_adaptive_quadratic_path(canvas, current, control, endpoint, tolerance, shape, color, alpha, context, segment_budget)
+          return endpoint
+        end
+
+        1.upto(detail) do |step|
+          break if segment_budget && segment_budget[:remaining] <= 0
+
+          t = step.to_f / detail
+          point = [
+            quadratic_point(current[0], control[0], endpoint[0], t),
+            quadratic_point(current[1], control[1], endpoint[1], t)
+          ]
+          draw_raw_path_segment(canvas, previous, point, shape, color, alpha, context, segment_budget)
+          previous = point
+        end
+        endpoint
+      end
+
+      def draw_cubic_path(canvas, current, values, detail, tolerance, shape, color, alpha, context, segment_budget = nil)
+        previous = current
+        c1 = values[0, 2]
+        c2 = values[2, 2]
+        endpoint = values[4, 2]
+        if tolerance
+          draw_adaptive_cubic_path(canvas, current, c1, c2, endpoint, tolerance, shape, color, alpha, context, segment_budget)
+          return endpoint
+        end
+
+        1.upto(detail) do |step|
+          break if segment_budget && segment_budget[:remaining] <= 0
+
+          t = step.to_f / detail
+          point = [
+            cubic_point(current[0], c1[0], c2[0], endpoint[0], t),
+            cubic_point(current[1], c1[1], c2[1], endpoint[1], t)
+          ]
+          draw_raw_path_segment(canvas, previous, point, shape, color, alpha, context, segment_budget)
+          previous = point
+        end
+        endpoint
+      end
+
+      def draw_arc_path(canvas, current, values, detail, shape, color, alpha, context, segment_budget = nil)
+        endpoint = values[5, 2]
+        arc = svg_arc_description(
+          from: current,
+          to: endpoint,
+          rx: values[0],
+          ry: values[1],
+          x_axis_rotation: values[2],
+          large_arc: arc_flag(values[3]),
+          sweep: arc_flag(values[4])
+        )
+        unless arc
+          return draw_raw_path_segment(canvas, current, endpoint, shape, color, alpha, context, segment_budget)
+        end
+
+        previous = current
+        segments = svg_arc_segment_count(arc, detail)
+        1.upto(segments) do |step|
+          break if segment_budget && segment_budget[:remaining] <= 0
+
+          point = svg_arc_point(arc, step.to_f / segments)
+          draw_raw_path_segment(canvas, previous, point, shape, color, alpha, context, segment_budget)
+          previous = point
+        end
+        endpoint
+      end
+
+      def path_segment_limit(shape)
+        raw_value = shape[:max_segments] || shape["max_segments"] || PATH_DEFAULT_MAX_SEGMENTS
+        [[Integer(raw_value), 1].max, PATH_HARD_MAX_SEGMENTS].min
+      rescue ArgumentError, TypeError
+        PATH_DEFAULT_MAX_SEGMENTS
+      end
+
+      def path_tolerance(shape)
+        return unless shape.key?(:tolerance) || shape.key?("tolerance")
+
+        value = Float(shape[:tolerance] || shape["tolerance"])
+        value if value.finite? && value >= 0
+      rescue ArgumentError, TypeError
+        nil
+      end
+
+      def draw_adaptive_quadratic_path(canvas, from, control, to, tolerance, shape, color, alpha, context, segment_budget, depth = 0)
+        return if segment_budget && segment_budget[:remaining] <= 0
+
+        if depth >= PATH_MAX_RECURSION || point_line_distance(control, from, to) <= tolerance
+          draw_raw_path_segment(canvas, from, to, shape, color, alpha, context, segment_budget)
+          return
+        end
+
+        left_control = midpoint(from, control)
+        right_control = midpoint(control, to)
+        center = midpoint(left_control, right_control)
+        draw_adaptive_quadratic_path(canvas, from, left_control, center, tolerance, shape, color, alpha, context, segment_budget, depth + 1)
+        draw_adaptive_quadratic_path(canvas, center, right_control, to, tolerance, shape, color, alpha, context, segment_budget, depth + 1)
+      end
+
+      def draw_adaptive_cubic_path(canvas, from, c1, c2, to, tolerance, shape, color, alpha, context, segment_budget, depth = 0)
+        return if segment_budget && segment_budget[:remaining] <= 0
+
+        flatness = [point_line_distance(c1, from, to), point_line_distance(c2, from, to)].max
+        if depth >= PATH_MAX_RECURSION || flatness <= tolerance
+          draw_raw_path_segment(canvas, from, to, shape, color, alpha, context, segment_budget)
+          return
+        end
+
+        p01 = midpoint(from, c1)
+        p12 = midpoint(c1, c2)
+        p23 = midpoint(c2, to)
+        p012 = midpoint(p01, p12)
+        p123 = midpoint(p12, p23)
+        center = midpoint(p012, p123)
+        draw_adaptive_cubic_path(canvas, from, p01, p012, center, tolerance, shape, color, alpha, context, segment_budget, depth + 1)
+        draw_adaptive_cubic_path(canvas, center, p123, p23, to, tolerance, shape, color, alpha, context, segment_budget, depth + 1)
+      end
+
+      def midpoint(from, to)
+        [(from[0] + to[0]) * 0.5, (from[1] + to[1]) * 0.5]
+      end
+
+      def point_line_distance(point, from, to)
+        dx = to[0] - from[0]
+        dy = to[1] - from[1]
+        length = Math.sqrt((dx * dx) + (dy * dy))
+        return Math.sqrt(((point[0] - from[0])**2) + ((point[1] - from[1])**2)) if length <= 0
+
+        ((dy * point[0]) - (dx * point[1]) + (to[0] * from[1]) - (to[1] * from[0])).abs / length
+      end
+
+      def draw_shape_segment(canvas, from, to, shape, color, alpha, context)
+        from = apply_shape_transform(from, shape, context)
+        to = apply_shape_transform(to, shape, context)
+        canvas.draw_line(from[0], from[1], to[0], to[1], color, alpha: alpha * shape_opacity(shape))
+      end
+
+      def shape_coordinate_context(params)
+        units = (params[:units] || params["units"]).to_s.strip.downcase
+        version = Integer(params[:shape_schema_version] || params["shape_schema_version"] || 1)
+        { units: (units.empty? ? (version >= 2 ? :logical : :legacy) : units.to_sym) }
+      rescue ArgumentError, TypeError
+        { units: :legacy }
+      end
+
+      def shape_point(x, y, context)
+        [shape_coordinate(x, context, :x), shape_coordinate(y, context, :y)]
+      end
+
+      def shape_coordinate(value, context, axis)
+        numeric = Float(value || 0)
+        case context[:units]
+        when :ndc
+          axis == :x ? width * 0.5 + numeric * width * 0.5 : height * 0.5 - numeric * height * 0.5
+        when :logical, :center, :center_origin, :px
+          axis == :x ? width * 0.5 + numeric : height * 0.5 - numeric
+        when :screen, :canvas, :viewport
+          numeric
+        else
+          legacy_shape_coordinate(numeric, axis)
+        end
+      end
+
+      def legacy_shape_coordinate(value, axis)
+        return axis == :x ? width * 0.5 + value * width * 0.5 : height * 0.5 - value * height * 0.5 if value.abs <= 1.5
+
+        value
+      end
+
+      def shape_length(value, context, _axis)
+        numeric = Float(value || 0).abs
+        return numeric * [width, height].min * 0.5 if context[:units] == :ndc || numeric <= 2
+
+        numeric
+      end
+
+      def circle_points(center, radius)
+        segments = 96
+        segments.times.map do |index|
+          angle = (index.to_f / segments) * Math::PI * 2
+          [center[0] + Math.cos(angle) * radius, center[1] + Math.sin(angle) * radius]
+        end
+      end
+
+      def apply_shape_transform(point, shape, context)
+        transform = shape_transform(shape, context)
+        shifted_x = (point[0] - transform[:origin][0]) * transform[:scale][:x]
+        shifted_y = (point[1] - transform[:origin][1]) * transform[:scale][:y]
+        radians = -transform[:rotate] * Math::PI / 180.0
+        cos = Math.cos(radians)
+        sin = Math.sin(radians)
+        rotated_x = shifted_x * cos - shifted_y * sin
+        rotated_y = shifted_x * sin + shifted_y * cos
+
+        [
+          rotated_x + transform[:origin][0] + transform[:translate][:x],
+          rotated_y + transform[:origin][1] + transform[:translate][:y]
+        ]
+      end
+
+      def shape_transform(shape, context)
+        transform = Hash(shape[:transform] || shape["transform"] || {})
+        {
+          translate: shape_vector_pair(shape_hash_value(transform, :translate) || shape_hash_value(shape, :translate), context),
+          origin: shape_origin_pair(shape_hash_value(transform, :origin) || shape_hash_value(shape, :origin), context),
+          rotate: Float(shape_hash_value(transform, :rotate) || shape_hash_value(shape, :rotate) || shape_hash_value(shape, :rotation) || 0),
+          scale: shape_scale(shape_hash_value(transform, :scale) || shape_hash_value(shape, :scale))
+        }
+      end
+
+      def shape_vector_pair(value, context)
+        if value.is_a?(Array)
+          return { x: shape_vector(value[0], context, :x), y: shape_vector(value[1], context, :y) }
+        end
+
+        values = value.is_a?(Hash) ? value : {}
+        { x: shape_vector(shape_hash_value(values, :x) || 0, context, :x), y: shape_vector(shape_hash_value(values, :y) || 0, context, :y) }
+      end
+
+      def shape_origin_pair(value, context)
+        if value.is_a?(Array)
+          return shape_point(value[0], value[1], context)
+        end
+
+        values = value.is_a?(Hash) ? value : {}
+        shape_point(shape_hash_value(values, :x) || 0, shape_hash_value(values, :y) || 0, context)
+      end
+
+      def shape_vector(value, context, axis)
+        numeric = Float(value || 0)
+        case context[:units]
+        when :ndc
+          axis == :x ? numeric * width * 0.5 : -numeric * height * 0.5
+        else
+          axis == :x ? numeric : -numeric
+        end
+      end
+
+      def shape_scale(value)
+        if value.is_a?(Hash)
+          return {
+            x: Float(shape_hash_value(value, :x) || 1).clamp(-8.0, 8.0),
+            y: Float(shape_hash_value(value, :y) || 1).clamp(-8.0, 8.0)
+          }
+        end
+
+        scale = Float(value || 1).clamp(-8.0, 8.0)
+        { x: scale, y: scale }
+      end
+
+      def shape_opacity(shape)
+        Float(shape[:opacity] || shape["opacity"] || 1).clamp(0.0, 1.0)
+      rescue ArgumentError, TypeError
+        1.0
+      end
+
+      def shape_hash_value(hash, key)
+        hash[key] || hash[key.to_s]
+      end
+
+      def quadratic_point(from, control, to, t)
+        inv = 1.0 - t
+        inv * inv * from + 2 * inv * t * control + t * t * to
+      end
+
+      def cubic_point(from, c1, c2, to, t)
+        inv = 1.0 - t
+        inv * inv * inv * from + 3 * inv * inv * t * c1 + 3 * inv * t * t * c2 + t * t * t * to
+      end
+
+      def svg_arc_description(from:, to:, rx:, ry:, x_axis_rotation:, large_arc:, sweep:)
+        return if same_point?(from, to)
+
+        radius_x = Float(rx || 0).abs
+        radius_y = Float(ry || 0).abs
+        return if radius_x <= 0 || radius_y <= 0
+
+        rotation = Float(x_axis_rotation || 0) * Math::PI / 180.0
+        cos = Math.cos(rotation)
+        sin = Math.sin(rotation)
+        dx = (from[0] - to[0]) / 2.0
+        dy = (from[1] - to[1]) / 2.0
+        x1p = cos * dx + sin * dy
+        y1p = -sin * dx + cos * dy
+
+        scale = (x1p * x1p / (radius_x * radius_x)) + (y1p * y1p / (radius_y * radius_y))
+        if scale > 1
+          multiplier = Math.sqrt(scale)
+          radius_x *= multiplier
+          radius_y *= multiplier
+        end
+
+        center = svg_arc_center(
+          from: from,
+          to: to,
+          radius_x: radius_x,
+          radius_y: radius_y,
+          x1p: x1p,
+          y1p: y1p,
+          rotation_cos: cos,
+          rotation_sin: sin,
+          large_arc: large_arc,
+          sweep: sweep
+        )
+        return unless center
+
+        start_vector = [(x1p - center[:cxp]) / radius_x, (y1p - center[:cyp]) / radius_y]
+        end_vector = [(-x1p - center[:cxp]) / radius_x, (-y1p - center[:cyp]) / radius_y]
+        start_angle = vector_angle([1.0, 0.0], start_vector)
+        delta_angle = vector_angle(start_vector, end_vector)
+        delta_angle -= Math::PI * 2 if !sweep && delta_angle.positive?
+        delta_angle += Math::PI * 2 if sweep && delta_angle.negative?
+
+        {
+          cx: center[:cx],
+          cy: center[:cy],
+          rx: radius_x,
+          ry: radius_y,
+          rotation: rotation,
+          start_angle: start_angle,
+          delta_angle: delta_angle
+        }
+      rescue ArgumentError, TypeError
+        nil
+      end
+
+      def svg_arc_center(from:, to:, radius_x:, radius_y:, x1p:, y1p:, rotation_cos:, rotation_sin:, large_arc:, sweep:)
+        rx2 = radius_x * radius_x
+        ry2 = radius_y * radius_y
+        x1p2 = x1p * x1p
+        y1p2 = y1p * y1p
+        denominator = rx2 * y1p2 + ry2 * x1p2
+        return if denominator.zero?
+
+        numerator = [rx2 * ry2 - rx2 * y1p2 - ry2 * x1p2, 0.0].max
+        sign = large_arc == sweep ? -1.0 : 1.0
+        coefficient = sign * Math.sqrt(numerator / denominator)
+        cxp = coefficient * ((radius_x * y1p) / radius_y)
+        cyp = coefficient * (-(radius_y * x1p) / radius_x)
+        {
+          cxp: cxp,
+          cyp: cyp,
+          cx: rotation_cos * cxp - rotation_sin * cyp + (from[0] + to[0]) / 2.0,
+          cy: rotation_sin * cxp + rotation_cos * cyp + (from[1] + to[1]) / 2.0
+        }
+      end
+
+      def svg_arc_point(arc, progress)
+        angle = arc[:start_angle] + arc[:delta_angle] * progress
+        cos_rotation = Math.cos(arc[:rotation])
+        sin_rotation = Math.sin(arc[:rotation])
+        x = Math.cos(angle) * arc[:rx]
+        y = Math.sin(angle) * arc[:ry]
+        [
+          arc[:cx] + cos_rotation * x - sin_rotation * y,
+          arc[:cy] + sin_rotation * x + cos_rotation * y
+        ]
+      end
+
+      def svg_arc_segment_count(arc, detail)
+        [((arc[:delta_angle].abs / (Math::PI * 2)) * detail).ceil, 1].max
+      end
+
+      def vector_angle(from, to)
+        cross = from[0] * to[1] - from[1] * to[0]
+        dot = from[0] * to[0] + from[1] * to[1]
+        Math.atan2(cross, dot)
+      end
+
+      def same_point?(from, to)
+        (from[0] - to[0]).abs < 1e-9 && (from[1] - to[1]).abs < 1e-9
+      end
+
+      def arc_flag(value)
+        !Float(value || 0).zero?
+      rescue ArgumentError, TypeError
+        false
       end
 
       def render_mesh_layer(canvas, layer, audio, color, index)

data/lib/vizcore/server/frame_broadcaster.rb

@@ -67,6 +67,8 @@ module Vizcore
         @error_reporter = error_reporter || ->(_message) {}
         @last_error = nil
         @frame_count = 0
+        @custom_shape_param_overrides = {}
+        @custom_shape_param_mutex = Mutex.new
         @transport_playing = initial_transport_playing_state
         reset_transition_trigger_counters!
         @tap_tempo = Vizcore::Analysis::TapTempo.new
@@ -210,18 +212,35 @@ module Vizcore
         true
       end
 
+      def set_custom_shape_param(layer_name:, custom_shape_index:, param:, value:)
+        layer_key = layer_name.to_s
+        param_key = param.to_s.strip
+        index = Integer(custom_shape_index)
+        numeric = finite_float(value)
+        return custom_shape_param_overrides_snapshot if layer_key.empty? || param_key.empty? || index.negative? || numeric.nil?
+
+        @custom_shape_param_mutex.synchronize do
+          @custom_shape_param_overrides[layer_key] ||= {}
+          @custom_shape_param_overrides[layer_key][index] ||= {}
+          @custom_shape_param_overrides[layer_key][index][param_key] = numeric
+          deep_dup(@custom_shape_param_overrides)
+        end
+      rescue ArgumentError, TypeError
+        custom_shape_param_overrides_snapshot
+      end
+
       # Build one frame payload for transport to frontend.
       #
       # @param _elapsed_seconds [Float]
       # @param samples [Array<Float>, nil]
       # @raise [Vizcore::FrameBuildError] when frame construction fails
       # @return [Hash]
-      def build_frame(_elapsed_seconds, samples = nil)
+      def build_frame(elapsed_seconds, samples = nil)
         started_at_ms = monotonic_ms
         audio_samples, audio_capture_ms = capture_or_use_samples(samples)
         analyzed, audio_analysis_ms = measure_ms { @analysis_pipeline.call(audio_samples) }
         scene = current_scene
-        layers, scene_build_ms = measure_ms { build_scene_layers(scene[:layers], analyzed) }
+        layers, scene_build_ms = measure_ms { build_scene_layers(scene[:layers], analyzed, time: elapsed_seconds, frame: @frame_count) }
 
         @scene_serializer.audio_frame(
           timestamp: Time.now.to_f,
@@ -293,10 +312,40 @@ module Vizcore
         value.positive? && (value & (value - 1)).zero?
       end
 
-      def build_scene_layers(scene_layers, analyzed)
+      def build_scene_layers(scene_layers, analyzed, time: 0.0, frame: 0)
         return default_scene_layers(analyzed) if scene_layers.empty?
 
-        @mapping_resolver.resolve_layers(scene_layers: scene_layers, audio: analyzed)
+        @mapping_resolver.resolve_layers(
+          scene_layers: scene_layers,
+          audio: analyzed,
+          time: time,
+          frame: frame,
+          custom_shape_overrides: custom_shape_param_overrides_snapshot
+        )
+      end
+
+      def custom_shape_param_overrides_snapshot
+        @custom_shape_param_mutex.synchronize { deep_dup(@custom_shape_param_overrides) }
+      end
+
+      def finite_float(value)
+        numeric = Float(value)
+        return nil unless numeric.finite?
+
+        numeric
+      rescue ArgumentError, TypeError
+        nil
+      end
+
+      def deep_dup(value)
+        case value
+        when Hash
+          value.each_with_object({}) { |(key, entry), output| output[key] = deep_dup(entry) }
+        when Array
+          value.map { |entry| deep_dup(entry) }
+        else
+          value
+        end
       end
 
       def default_scene_layers(analyzed)

data/lib/vizcore/server/runner.rb

@@ -398,6 +398,8 @@ module Vizcore
           switch_scene_from_client(target_name, broadcaster)
         when "tap_tempo"
           apply_tap_tempo(payload, broadcaster)
+        when "custom_shape_param"
+          apply_custom_shape_param(payload, broadcaster)
         end
       rescue StandardError => e
         @output.puts(Vizcore::ErrorFormatting.summarize(e, context: "Client control message failed"))
@@ -616,6 +618,25 @@ module Vizcore
         )
       end
 
+      def apply_custom_shape_param(payload, broadcaster)
+        return unless broadcaster.respond_to?(:set_custom_shape_param)
+
+        values = Hash(payload)
+        overrides = broadcaster.set_custom_shape_param(
+          layer_name: values["layer"] || values[:layer] || values["layer_name"] || values[:layer_name],
+          custom_shape_index: values["custom_shape_index"] || values[:custom_shape_index] || values["index"] || values[:index],
+          param: values["param"] || values[:param],
+          value: values["value"] || values[:value]
+        )
+        WebSocketHandler.broadcast(
+          type: "config_update",
+          payload: {
+            custom_shape_params: overrides,
+            source: "ui"
+          }
+        )
+      end
+
       def apply_osc_live_control(control, value)
         @live_controls[control] = osc_truthy?(value)
         WebSocketHandler.broadcast(