vizcore 1.0.0 → 1.1.0

data/lib/vizcore/dsl/layer_builder.rb

@@ -2,15 +2,52 @@
 
 require_relative "mapping_transform_builder"
 require_relative "reaction_builder"
+require_relative "../shape"
 
 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
       ].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
+
+      # 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
@@ -24,6 +61,8 @@ module Vizcore
         @params = deep_dup(defaults)
         @param_schema = {}
         @mappings = []
+        @shape_index_by_id = {}
+        @shape_group_stack = [{}]
       end
 
       # Evaluate a layer block.
@@ -72,8 +111,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 +120,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 +310,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 +340,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 +371,193 @@ 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) { raise ArgumentError, "unknown shape id: #{key.inspect}" }
+        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"
@@ -232,6 +610,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)
@@ -405,6 +784,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 +803,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 +882,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 +1194,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 +1261,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