elkrb 1.0.0 → 2.0.0

data/lib/elkrb/options/element_options.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "option_map"
+require_relative "registry"
+
+module Elkrb
+  module Options
+    # @api private
+    #
+    # The option maps of one element, in the order Resolver#get reads them:
+    # layoutOptions, the deprecated map nested in it, then properties.
+    # Resolver#get and UnhonouredReport both take their sources from here, so
+    # a source added to this list is read and reported together.
+    class ElementOptions
+      # @param element [#layout_options, #properties, nil]
+      # @param spellings [Spellings]
+      def initialize(element, spellings)
+        @layout = OptionMap.new(element&.layout_options, spellings)
+        @properties = OptionMap.new(element&.properties, spellings)
+        @read_order = [@layout, @layout.nested, @properties].compact
+      end
+
+      # @return [Object, nil] the first non-nil value for a canonical id; an
+      #   explicit false is a value
+      def value(id)
+        @read_order.each do |map|
+          found = map.value(id)
+          return found unless found.nil?
+        end
+        nil
+      end
+
+      # Every canonical id the element names as an option: all keys of
+      # layoutOptions, nested ones included, and the registered keys of
+      # properties. An unknown name in properties is metadata, not an option.
+      #
+      # @return [Array<String>]
+      def ids
+        @layout.ids + @properties.own_ids.select { |id| Registry.status(id) }
+      end
+    end
+  end
+end

data/lib/elkrb/options/elk_padding.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "decimal"
+
 module Elkrb
   module Options
     # ElkPadding parser for padding specifications
@@ -10,10 +12,10 @@ module Elkrb
       attr_reader :left, :top, :right, :bottom
 
       def initialize(left: 0, top: 0, right: 0, bottom: 0)
-        @left = left.to_f
-        @top = top.to_f
-        @right = right.to_f
-        @bottom = bottom.to_f
+        @left = Decimal.to_f(left)
+        @top = Decimal.to_f(top)
+        @right = Decimal.to_f(right)
+        @bottom = Decimal.to_f(bottom)
       end
 
       # Parse padding from string or hash
@@ -34,10 +36,9 @@ module Elkrb
       # @return [ElkPadding] Parsed padding object
       def self.from_hash(hash)
         new(
-          left: hash[:left] || hash["left"] || 0,
-          top: hash[:top] || hash["top"] || 0,
-          right: hash[:right] || hash["right"] || 0,
-          bottom: hash[:bottom] || hash["bottom"] || 0,
+          **%i[left top right bottom].to_h do |side|
+            [side, Decimal.component(hash, side, 0)]
+          end,
         )
       end
 
@@ -46,17 +47,22 @@ module Elkrb
       # @param str [String] String like "[left=2, top=3, right=3, bottom=2]"
       # @return [ElkPadding] Parsed padding object
       def self.from_string(str)
-        # Remove brackets and split by comma
         content = str.strip.gsub(/^\[|\]$/, "")
-        parts = {}
+        new(**content.split(",", -1).to_h { |entry| side_and_number(entry) })
+      end
 
-        content.split(",").each do |part|
-          key, value = part.split("=").map(&:strip)
-          parts[key.to_sym] = value.to_f
+      # One "side=number" entry, validated here so a repeated side cannot
+      # hide a malformed earlier value; an entry without exactly one '=' is
+      # malformed.
+      def self.side_and_number(entry)
+        key, value, extra = entry.split("=", -1).map(&:strip)
+        if extra || !value
+          raise ArgumentError, "Invalid padding entry: #{entry.inspect}"
         end
 
-        new(**parts)
+        [key.to_sym, Decimal.to_f(value)]
       end
+      private_class_method :side_and_number
 
       # Convert to hash
       #

data/lib/elkrb/options/k_vector.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "decimal"
+
 module Elkrb
   module Options
     # KVector parser for coordinate pairs
@@ -10,8 +12,8 @@ module Elkrb
       attr_reader :x, :y
 
       def initialize(x, y)
-        @x = x.to_f
-        @y = y.to_f
+        @x = Decimal.to_f(x)
+        @y = Decimal.to_f(y)
       end
 
       # Parse KVector from string, hash, or array
@@ -32,10 +34,7 @@ module Elkrb
       # @param hash [Hash] Hash with :x and :y keys
       # @return [KVector] Parsed coordinate object
       def self.from_hash(hash)
-        new(
-          hash[:x] || hash["x"] || 0,
-          hash[:y] || hash["y"] || 0,
-        )
+        new(Decimal.component(hash, :x, 0), Decimal.component(hash, :y, 0))
       end
 
       # Parse from array
@@ -55,7 +54,7 @@ module Elkrb
       def self.from_string(str)
         # Remove parentheses and split by comma
         content = str.strip.gsub(/^\(|\)$/, "")
-        parts = content.split(",").map(&:strip)
+        parts = content.split(",", -1).map(&:strip)
 
         unless parts.size == 2
           raise ArgumentError,

data/lib/elkrb/options/k_vector_chain.rb

@@ -37,30 +37,22 @@ module Elkrb
 
       # Parse from string
       #
-      # @param str [String] String like "( {1,2}, {3,4} )"
+      # Mirrors ELK's own KVectorChain parser: split on any run of comma,
+      # semicolon, and bracket/brace/paren characters (plus whitespace),
+      # then group the resulting tokens into pairs; KVector rejects a token
+      # that is not a plain decimal number. Accepts every
+      # bracket style elkrb previously emitted as well as ELK's own
+      # canonical "(x,y; x,y)" output.
+      #
+      # @param str [String] e.g. "(1,2; 3,4)", "({1,2},{3,4})", "(1,2),(3,4)"
       # @return [KVectorChain] Parsed coordinate chain object
       def self.from_string(str)
-        # Remove outer parentheses
-        content = str.strip.gsub(/^\(\s*|\s*\)$/, "")
-
-        # Split by },{  or } , {
-        parts = content.split(/\}\s*,\s*\{/)
-
-        # Clean up first and last parts
-        parts[0] = parts[0].sub(/^\{/, "") if parts[0]
-        parts[-1] = parts[-1].sub(/\}$/, "") if parts[-1]
-
-        # Parse each coordinate pair
-        vectors = parts.map do |part|
-          coords = part.split(",").map(&:strip)
-          unless coords.size == 2
-            raise ArgumentError,
-                  "Invalid coordinate pair: #{part}"
-          end
-
-          KVector.new(coords[0], coords[1])
+        tokens = str.split(/[,;()\[\]{}\s]+/).reject(&:empty?)
+        unless tokens.size.even?
+          raise ArgumentError, "Invalid KVectorChain format: #{str}"
         end
 
+        vectors = tokens.each_slice(2).map { |x, y| KVector.new(x, y) }
         new(vectors)
       end
 

data/lib/elkrb/options/option_map.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require_relative "spellings"
+
+module Elkrb
+  module Options
+    # @api private
+    #
+    # One option map read once into { canonical id => value }. Read option
+    # maps only through this table: it walks with each_pair, so a Hash
+    # default is never a value, and it folds String and Symbol keys and every
+    # spelling of an id. The best spelling wins, then a String over a Symbol,
+    # then the first inserted, which only two keys of another class can reach.
+    # A nil value is a miss, but its id still counts as present for the report.
+    class OptionMap
+      NESTED_KEY = "properties"
+      STRING_KEY = 0
+      OTHER_KEY = 1
+      private_constant :STRING_KEY, :OTHER_KEY
+
+      # @param map [Hash, nil] anything else reads as an empty map
+      # @param spellings [Spellings]
+      def initialize(map, spellings)
+        @spellings = spellings
+        @ids = {}
+        @best = {}
+        map.each_pair { |key, value| add(key, value) } if map.is_a?(Hash)
+      end
+
+      # @return [Object, nil] the raw value for a canonical id; nil is a miss
+      def value(id)
+        @best[id]&.last
+      end
+
+      # The deprecated map inside layoutOptions that older graphs nest
+      # options under. Only a Hash counts; it is read after the map's own
+      # keys.
+      #
+      # @return [OptionMap, nil]
+      def nested
+        return @nested if defined?(@nested)
+
+        raw = value(nested_id)
+        @nested = raw.is_a?(Hash) ? self.class.new(raw, @spellings) : nil
+      end
+
+      # Every canonical id the map names, nested properties included, in
+      # first-seen order. A nested map replaces its own "properties" key.
+      #
+      # @return [Array<String>]
+      def ids
+        inner = nested
+        return own_ids unless inner
+
+        own_ids - [nested_id] + inner.own_ids
+      end
+
+      # The canonical ids of the map's own keys, without the nested
+      # properties map.
+      #
+      # @return [Array<String>]
+      def own_ids
+        @ids.keys
+      end
+
+      private
+
+      def nested_id
+        @spellings.id(NESTED_KEY)
+      end
+
+      def add(key, value)
+        id, spelling_rank = @spellings.resolve(key)
+        @ids[id] = true
+        return if value.nil?
+
+        rank = [spelling_rank, key.is_a?(String) ? STRING_KEY : OTHER_KEY]
+        held = @best[id]
+        return unless held.nil? || (rank <=> held.first).negative?
+
+        @best[id] = [rank, value]
+      end
+    end
+  end
+end

data/lib/elkrb/options/registry.rb

@@ -0,0 +1,335 @@
+# frozen_string_literal: true
+
+require_relative "decimal"
+require_relative "elk_padding"
+require_relative "k_vector"
+require_relative "k_vector_chain"
+require_relative "../errors"
+
+module Elkrb
+  module Options
+    # Single source of truth for ELK/elkrb layout option metadata: id,
+    # type, default, allowed values, aliases, owning algorithms, and the
+    # elkrb 2.0 truthfulness status. Elkrb.known_layout_options,
+    # LayoutEngine.known_layout_options, and AlgorithmRegistry#algorithm_info
+    # all read from OPTIONS through the methods below — nothing else does.
+    class Registry
+      ELK_PREFIX = "org.eclipse.elk."
+      BOOLEAN_LITERALS = [true, false].freeze
+      private_constant :BOOLEAN_LITERALS
+      private_constant :ELK_PREFIX
+
+      # A :partial row either lists `readers`, the algorithms that read the id
+      # on every applicable carrier (the id is partial ACROSS algorithms), or
+      # lists none (it is partial WITHIN each algorithm). `carriers` narrows
+      # where a reader consumes the id. With `readers`, `note` holds only what
+      # the list leaves out; .note joins the two.
+      #
+      # The OPTIONS constant name/path is private; .all below returns
+      # this same frozen object, so use .all (or .canonical/.coerce/
+      # .default/.status/.note/.for_algorithm) rather than reaching for
+      # the constant directly. Rows are sorted by id; insert new rows in
+      # sorted position, never at the end.
+      # rubocop:disable Layout/LineLength
+      OPTIONS = {
+        "disco.componentAlgorithm" => { type: :string, default: "layered", namespace: :elkrb, algorithms: %w[disco], status: :honoured, description: "Algorithm used to lay out each component" },
+        "disco.componentArrangement" => { type: :string, values: %w[row column grid], default: "row", namespace: :elkrb, algorithms: %w[disco], status: :honoured, description: "How components are arranged" },
+        "disco.componentSpacing" => { type: :float, default: 20.0, namespace: :elkrb, algorithms: %w[disco], status: :honoured, description: "Spacing between components" },
+        "elk.algorithm" => { type: :string, default: "layered", aliases: %w[algorithm], algorithms: :all, status: :honoured, description: "The layout algorithm to use" },
+        "elk.aspectRatio" => { type: :float, default: 1.6, aliases: %w[aspectRatio aspect_ratio], algorithms: %w[box disco layered random], status: :honoured, description: "Target width/height ratio (box, disco, layered, random)" },
+        "elk.bendPoints" => { type: :kvector_chain, default: nil, aliases: %w[bendPoints], algorithms: :all, status: :partial, readers: %w[fixed], carriers: %i[edge call], note: "No other algorithm applies explicit bend points", description: "Manual bend points for an edge" },
+        "elk.box.packingMode" => { type: :enum, values: %w[SIMPLE GROUP_DEC GROUP_MIXED GROUP_INC], default: "SIMPLE", algorithms: %w[box], status: :accepted, description: "Box layout packing mode; SIMPLE is implemented and GROUP_* values fall back to it" },
+        "elk.compaction.orthogonal" => { type: :boolean, default: false, aliases: %w[compaction.orthogonal], algorithms: %w[spore_compaction], status: :honoured, description: "Whether SPOrE compaction slides subtrees along one axis only" },
+        "elk.direction" => { type: :enum, values: %w[UNDEFINED RIGHT LEFT DOWN UP], value_aliases: { "HORIZONTAL" => "RIGHT", "VERTICAL" => "DOWN" }, default: "RIGHT", aliases: %w[direction], algorithms: %w[layered mrtree], status: :partial, readers: %w[layered mrtree], carriers: %i[root compound call], note: "Parent and call options drive node placement; HORIZONTAL and VERTICAL are accepted elkrb spline-orientation aliases and normalize to RIGHT and DOWN; DOT export reads every registered spelling from the graph's layoutOptions", description: "Overall direction of layout" },
+        "elk.disco.componentCompaction.strategy" => { type: :enum, values: %w[POLYOMINO], accepted_values: %w[POLYOMINO ROW COLUMN GRID], default: "POLYOMINO", algorithms: %w[disco], status: :honoured, description: "DisCo component compaction; POLYOMINO packs components as polyominoes, with edges counted as straight lines between their end nodes. ROW, COLUMN and GRID are accepted elkrb extensions matching disco.componentArrangement" },
+        "elk.edgeLabels.placement" => { type: :string, default: "CENTER", algorithms: :all, status: :honoured, description: "Edge label placement" },
+        "elk.edgeRouting" => { type: :enum, values: %w[UNDEFINED POLYLINE ORTHOGONAL SPLINES], default: "UNDEFINED", aliases: %w[edgeRouting edge_routing edge.routing], algorithms: :all, status: :partial, readers: %w[box disco force layered mrtree radial rectpacking spore_compaction spore_overlap stress topdownpacking vertiflex], carriers: %i[root compound edge call], note: "Fixed preserves existing edge routes. libavoid routes every edge between two nodes of a level itself as an orthogonal route around the nodes and ignores the style for them; its self-loops and edges that leave the level follow the style like any other algorithm's edges", description: "Edge routing style" },
+        "elk.force.iterations" => { type: :integer, default: 300, aliases: %w[iterations], algorithms: %w[force], status: :honoured, description: "Force simulation iteration count" },
+        "elk.force.repulsion" => { type: :float, default: 5.0, aliases: %w[repulsion], algorithms: %w[force], status: :honoured, description: "Force simulation repulsion strength" },
+        "elk.force.temperature" => { type: :float, default: 0.001, aliases: %w[temperature], algorithms: %w[force], status: :honoured, description: "Force simulation cooling temperature" },
+        "elk.hierarchyHandling" => { type: :enum, values: %w[INHERIT INCLUDE_CHILDREN SEPARATE_CHILDREN], default: "INHERIT", algorithms: :all, status: :partial, note: "cross-level edges are routed; no cross-level layering", description: "Whether a compound node's children are laid out separately or together with it" },
+        "elk.layered.compaction.postCompaction.strategy" => { type: :enum, values: %w[NONE LEFT RIGHT LEFT_RIGHT_CONSTRAINT_LOCKING LEFT_RIGHT_CONNECTION_LOCKING EDGE_LENGTH], default: "NONE", algorithms: %w[layered], status: :accepted, description: "Post-layout compaction strategy; not honoured today" },
+        "elk.layered.considerModelOrder.strategy" => { type: :enum, values: %w[NONE NODES_AND_EDGES PREFER_EDGES PREFER_NODES], default: "NONE", algorithms: %w[layered], status: :honoured, description: "Whether to preserve model node/edge order as a crossing-minimization tie-break" },
+        "elk.layered.crossingMinimization.strategy" => { type: :enum, values: %w[LAYER_SWEEP MEDIAN_LAYER_SWEEP INTERACTIVE NONE], default: "LAYER_SWEEP", algorithms: %w[layered], status: :honoured, description: "Crossing minimization strategy; NONE skips the sweeps and keeps only the greedy switch, other values use layer sweep" },
+        "elk.layered.layering.layerConstraint" => { type: :enum, values: %w[NONE FIRST FIRST_SEPARATE LAST LAST_SEPARATE], default: "NONE", algorithms: %w[layered], status: :honoured, description: "Forces a node to the first or last layer" },
+        "elk.layered.nodePlacement.strategy" => { type: :enum, values: %w[SIMPLE INTERACTIVE LINEAR_SEGMENTS BRANDES_KOEPF NETWORK_SIMPLEX], default: "BRANDES_KOEPF", algorithms: %w[layered], status: :accepted, description: "Node placement strategy; not honoured today (elkrb places nodes with BRANDES_KOEPF only, every value falls back to it)" },
+        "elk.layered.spacing.nodeNodeBetweenLayers" => { type: :float, default: 20.0, aliases: %w[layer_spacing layered.spacing.nodeNodeBetweenLayers], algorithms: %w[layered], status: :honoured, description: "Spacing between layers" },
+        "elk.nodeLabels.placement" => { type: :string, default: "INSIDE CENTER", aliases: %w[node.label.placement label.placement], algorithms: :all, status: :honoured, description: "Node label placement" },
+        "elk.padding" => { type: :padding, default: "[top=12,left=12,bottom=12,right=12]", aliases: %w[padding], algorithms: :all, status: :honoured, description: "Padding around the graph" },
+        "elk.port.index" => { type: :integer, default: -1, aliases: %w[port.index], algorithms: :all, status: :honoured, description: "Order of a port among its side's ports" },
+        "elk.port.side" => { type: :enum, values: %w[NORTH SOUTH EAST WEST UNDEFINED], default: "UNDEFINED", aliases: %w[port.side], algorithms: :all, status: :honoured, description: "Side of the node a port is attached to" },
+        "elk.portConstraints" => { type: :enum, values: %w[UNDEFINED FREE FIXED_SIDE FIXED_ORDER FIXED_RATIO FIXED_POS], default: "UNDEFINED", aliases: %w[portConstraints], algorithms: :all, status: :honoured, description: "How strictly port positions are respected" },
+        "elk.portLabels.placement" => { type: :string, default: "OUTSIDE", aliases: %w[port.label.placement], algorithms: :all, status: :honoured, description: "Port label placement" },
+        "elk.position" => { type: :kvector, default: nil, aliases: %w[position], algorithms: %w[fixed], status: :honoured, description: "Fixed position for a node (fixed algorithm)" },
+        "elk.processingOrder.preferredRoot" => { type: :string, default: nil, aliases: %w[processingOrder.preferredRoot], algorithms: %w[spore_compaction], status: :honoured, description: "Id of the node the SPOrE spanning tree grows from (rootSelection FIXED)" },
+        "elk.processingOrder.rootSelection" => { type: :enum, values: %w[FIXED CENTER_NODE], default: "CENTER_NODE", aliases: %w[processingOrder.rootSelection], algorithms: %w[spore_compaction], status: :honoured, description: "How the SPOrE spanning tree's root node is chosen" },
+        "elk.processingOrder.spanningTreeCostFunction" => { type: :enum, values: %w[CENTER_DISTANCE CIRCLE_UNDERLAP RECTANGLE_UNDERLAP INVERTED_OVERLAP MINIMUM_ROOT_DISTANCE], default: "CIRCLE_UNDERLAP", aliases: %w[processingOrder.spanningTreeCostFunction], algorithms: %w[spore_compaction], status: :honoured, description: "Edge cost the SPOrE spanning tree minimises" },
+        "elk.processingOrder.treeConstruction" => { type: :enum, values: %w[MINIMUM_SPANNING_TREE MAXIMUM_SPANNING_TREE], default: "MINIMUM_SPANNING_TREE", aliases: %w[processingOrder.treeConstruction], algorithms: %w[spore_compaction], status: :honoured, description: "Whether the SPOrE spanning tree is a minimum or a maximum one" },
+        "elk.radial.centerOnRoot" => { type: :boolean, default: false, algorithms: %w[radial], status: :honoured, description: "Whether the root node is placed at the centre" },
+        "elk.radial.radius" => { type: :float, default: 100.0, algorithms: %w[radial], status: :honoured, description: "Radius for radial layout" },
+        "elk.randomSeed" => { type: :integer, default: 1, aliases: %w[randomSeed], algorithms: %w[force random], status: :honoured, description: "Seed for algorithms with random behaviour" },
+        "elk.selfLoopOffset" => { type: :float, default: 20.0, aliases: %w[selfLoopOffset], namespace: :elkrb, algorithms: :all, status: :partial, readers: %w[box disco force layered libavoid mrtree radial rectpacking spore_compaction spore_overlap stress topdownpacking vertiflex], carriers: %i[node edge call], note: "Fixed preserves existing edge routes", description: "elkrb-private: distance between a self-loop and its node; the nth loop on a node sits at n times this distance" },
+        "elk.selfLoopRouting" => { type: :string, default: nil, aliases: %w[selfLoopRouting], namespace: :elkrb, algorithms: :all, status: :accepted, description: "elkrb-private: no routing styles are defined, so every value is ignored; a self-loop follows elk.edgeRouting" },
+        "elk.selfLoopSide" => { type: :enum, values: %w[NORTH SOUTH EAST WEST], default: "EAST", aliases: %w[selfLoopSide], namespace: :elkrb, algorithms: :all, status: :partial, readers: %w[box disco force layered libavoid mrtree radial rectpacking spore_compaction spore_overlap stress topdownpacking vertiflex], carriers: %i[node edge call], note: "Fixed preserves existing edge routes", description: "elkrb-private: side a self-loop is drawn on" },
+        "elk.separateConnectedComponents" => { type: :boolean, default: true, algorithms: %w[layered], status: :honoured, description: "Whether each connected component is laid out on its own and the components are packed in rows" },
+        "elk.spacing.componentComponent" => { type: :float, default: 20.0, algorithms: %w[disco layered], status: :honoured, description: "Spacing between disconnected components" },
+        "elk.spacing.edgeEdge" => { type: :float, default: 10.0, algorithms: %w[layered], status: :accepted, description: "Spacing between two edges; not honoured today" },
+        "elk.spacing.edgeNode" => { type: :float, default: 10.0, algorithms: %w[layered], status: :accepted, description: "Spacing between an edge and a node it does not connect to; not honoured today" },
+        "elk.spacing.nodeNode" => { type: :float, default: 20.0, aliases: %w[spacing.nodeNode spacing_node_node], algorithms: :all, status: :partial, readers: %w[box force layered mrtree random rectpacking spore_compaction topdownpacking vertiflex], carriers: %i[root compound call], note: "Every reader takes it under every spelling, from the call options and from the layoutOptions of the graph or compound node it lays out. libavoid also reads it, unless every node has an input position; disco reads it only from a compound node's layoutOptions. SPOrE compaction reads it unless spore.nodeSpacing is set, and moves nothing while no node has an input position. No other algorithm reads it", description: "Spacing between nodes" },
+        "elk.spline.curvature" => { type: :float, default: 0.5, aliases: %w[spline.curvature], namespace: :elkrb, algorithms: :all, status: :partial, readers: %w[box disco force layered rectpacking spore_compaction spore_overlap stress topdownpacking vertiflex], carriers: %i[edge call], note: "Fixed preserves routes; MRTree and Radial replace generic spline routing; libavoid does not apply it to edges between two nodes of a level, which it routes itself as orthogonal routes", description: "elkrb-private: curvature factor for SPLINES routing" },
+        "elk.stress.desiredEdgeLength" => { type: :float, default: 100.0, algorithms: %w[stress], status: :honoured, description: "Desired edge length for stress majorization" },
+        "elk.stress.epsilon" => { type: :float, default: 0.001, aliases: %w[epsilon], algorithms: %w[stress], status: :honoured, description: "Stress majorization convergence threshold" },
+        "elk.stress.iterationLimit" => { type: :integer, default: 2_147_483_647, algorithms: %w[stress], status: :honoured, description: "Stress majorization iteration limit" },
+        "label.margin" => { type: :float, default: 5.0, namespace: :elkrb, algorithms: :all, status: :honoured, description: "elkrb-private: outer label margin" },
+        "label.padding" => { type: :float, default: 5.0, namespace: :elkrb, algorithms: :all, status: :honoured, description: "elkrb-private: inner label padding" },
+        "label.placement.disabled" => { type: :boolean, default: false, namespace: :elkrb, algorithms: :all, status: :honoured, description: "elkrb-private: skip automatic label placement entirely" },
+        "libavoid.bendPenalty" => { type: :float, default: 2.0, namespace: :elkrb, algorithms: %w[libavoid], status: :honoured, description: "Penalty per bend in a routed connector" },
+        "libavoid.maxExpansions" => { type: :integer, default: 2000, namespace: :elkrb, algorithms: %w[libavoid], status: :honoured, description: "Search expansions per edge before falling back to a direct line" },
+        "libavoid.routingPadding" => { type: :float, default: 10.0, namespace: :elkrb, algorithms: %w[libavoid], status: :honoured, description: "Obstacle padding for connector routing" },
+        "libavoid.segmentPenalty" => { type: :float, default: 1.0, namespace: :elkrb, algorithms: %w[libavoid], status: :honoured, description: "Penalty per routed segment" },
+        "libavoid.stepSize" => { type: :float, default: 10.0, namespace: :elkrb, algorithms: %w[libavoid], status: :honoured, description: "Grid step of the connector search" },
+        "spore.compactionDirection" => { type: :string, values: %w[both horizontal vertical], default: "both", namespace: :elkrb, algorithms: %w[spore_compaction], status: :honoured, description: "Axis SPOrE compaction slides subtrees along; both is ELK's own behaviour" },
+        "spore.maxIterations" => { type: :integer, default: 64, namespace: :elkrb, algorithms: %w[spore_overlap], status: :honoured, description: "Maximum overlap-removal iterations" },
+        "spore.nodeSpacing" => { type: :float, default: 10.0, namespace: :elkrb, algorithms: %w[spore_overlap spore_compaction], status: :honoured, description: "Minimum spacing enforced by the SPOrE algorithms" },
+        "topdownpacking.aspectRatio" => { type: :float, default: 1.0, namespace: :elkrb, algorithms: %w[topdownpacking], status: :honoured, description: "Target cell aspect ratio" },
+        "topdownpacking.nodeWidth" => { type: :float, default: nil, namespace: :elkrb, algorithms: %w[topdownpacking], status: :honoured, description: "Explicit node width override" },
+        "vertiflex.balanceColumns" => { type: :boolean, default: true, namespace: :elkrb, algorithms: %w[vertiflex], status: :honoured, description: "Balance node counts across columns" },
+        "vertiflex.columnCount" => { type: :integer, default: 3, namespace: :elkrb, algorithms: %w[vertiflex], status: :honoured, description: "Number of columns" },
+        "vertiflex.columnSpacing" => { type: :float, default: 50.0, namespace: :elkrb, algorithms: %w[vertiflex], status: :honoured, description: "Spacing between columns" },
+        "vertiflex.verticalSpacing" => { type: :float, default: 30.0, namespace: :elkrb, algorithms: %w[vertiflex], status: :honoured, description: "Spacing between nodes within a column" },
+      }.freeze
+      # rubocop:enable Layout/LineLength
+      private_constant :OPTIONS
+
+      # LayoutEngine, not the algorithm, honours the selector — so it applies
+      # to every registration, including a custom class that inherits no
+      # BaseAlgorithm mixins and therefore gets none of the shared ids.
+      ENGINE_OPTIONS = %w[elk.algorithm].freeze
+      private_constant :ENGINE_OPTIONS
+
+      OPTIONS.each_value do |entry|
+        entry.freeze
+        entry[:aliases]&.freeze
+        entry[:values]&.freeze
+        entry[:accepted_values]&.freeze
+        entry[:value_aliases]&.freeze
+        entry[:algorithms].freeze if entry[:algorithms].is_a?(Array)
+        entry[:readers]&.freeze
+        entry[:carriers]&.freeze
+      end
+
+      ALIAS_LOOKUP = OPTIONS.each_with_object({}) do |(id, entry), lookup|
+        Array(entry[:aliases]).each { |a| lookup[a] = id }
+      end.freeze
+      private_constant :ALIAS_LOOKUP
+
+      class << self
+        # @param key [String, Symbol] any id, alias, or ELK-prefixed id
+        # @return [String, nil] the canonical id, or nil if unknown
+        def canonical(key)
+          key_str = key.to_s
+          return key_str if OPTIONS.key?(key_str)
+
+          if key_str.start_with?(ELK_PREFIX)
+            stripped = key_str.sub(ELK_PREFIX, "elk.")
+            return stripped if OPTIONS.key?(stripped)
+          end
+
+          return ALIAS_LOOKUP[key_str] if ALIAS_LOOKUP.key?(key_str)
+
+          suffix_match(key_str)
+        end
+
+        # @param id [String, Symbol] any id or alias
+        # @param value [Object] the raw value to coerce
+        # @return [Object] value coerced to the id's registered type
+        def coerce(id, value)
+          entry = entry_for(id)
+          return value unless entry
+
+          coerce_typed(entry[:type], value, entry, canonical(id))
+        end
+
+        # @param id [String, Symbol] any id or alias
+        # @return [Object, nil] the id's default, coerced to its type
+        def default(id)
+          entry = entry_for(id)
+          return nil unless entry
+          return nil if entry[:default].nil?
+
+          coerce_typed(entry[:type], entry[:default], entry, canonical(id))
+        end
+
+        # @param id [String, Symbol] any id or alias
+        # @return [Symbol, nil] :honoured, :partial, :accepted, :unsupported, or nil if unknown
+        def status(id)
+          entry_for(id)&.[](:status)
+        end
+
+        # @param id [String, Symbol] any id or alias
+        # @return [String, nil] explanatory note for a :partial id; for an id
+        #   with readers it names them first
+        def note(id)
+          entry = entry_for(id)
+          return unless entry
+          return entry[:note] unless entry[:readers]
+
+          "Read by #{entry[:readers].join(', ')}. #{entry[:note]}"
+        end
+
+        # @param id [String, Symbol] any id or alias
+        # @param algorithm [String, nil] a normalised algorithm name
+        # @param carrier [Symbol, nil] where the option is written; nil checks
+        #   only algorithm readership
+        # @return [Boolean] whether the id lists the algorithm among its
+        #   readers; false for an id with no readers. Readers are the
+        #   built-in algorithms, matched by registered name: a class
+        #   registered under another name is not one, and a class registered
+        #   over a built-in name is taken to read what that name reads.
+        def read_by?(id, algorithm, carrier: nil)
+          entry = entry_for(id)
+          return false unless Array(entry&.[](:readers)).include?(algorithm)
+
+          carrier.nil? || Array(entry[:carriers]).include?(carrier)
+        end
+
+        # Membership, not truthfulness: an id's presence here means it's
+        # scoped to this algorithm, regardless of whether it's currently
+        # honoured, accepted, or unsupported — cross-reference #status(id)
+        # for that.
+        #
+        # @param name [String] a normalised algorithm name (e.g. "layered")
+        # @param include_all [Boolean] whether to include algorithms: :all
+        #   ids (AlgorithmRegistry passes false for a registration that
+        #   does not inherit BaseAlgorithm, so does not get those for free)
+        # @return [Array<String>] canonical ids scoped to that algorithm
+        def for_algorithm(name, include_all: true)
+          OPTIONS.select do |id, entry|
+            ENGINE_OPTIONS.include?(id) ||
+              (include_all && entry[:algorithms] == :all) ||
+              Array(entry[:algorithms]).include?(name)
+          end.keys
+        end
+
+        # @return [Hash] the full, frozen options table
+        def all
+          OPTIONS
+        end
+
+        # Renders OPTIONS into the documented shape Elkrb.known_layout_options
+        # and LayoutEngine.known_layout_options both return. The single
+        # owner of that rendering — the two callers are one-line
+        # delegators, mirroring how they already both delegate straight to
+        # AlgorithmRegistry.all_algorithm_info for known_layout_algorithms.
+        #
+        # @param algorithm_values [Array<String>] registered algorithm ids,
+        #   patched onto the elk.algorithm row's :values. Passed in rather
+        #   than read from AlgorithmRegistry directly, so Options never
+        #   depends on Layout.
+        # @return [Hash{String => Hash}] canonical id => {type:, description:,
+        #   default:, values:, parser:, status:, note:}
+        def render_known_options(algorithm_values:)
+          parsers = {
+            padding: "Elkrb::Options::ElkPadding",
+            kvector: "Elkrb::Options::KVector",
+            kvector_chain: "Elkrb::Options::KVectorChain",
+          }
+
+          rendered = OPTIONS.each_with_object({}) do |(id, entry), hash|
+            hash[id] = {
+              type: entry[:type],
+              description: entry[:description],
+              default: entry[:default],
+              values: entry[:values],
+              parser: parsers[entry[:type]],
+              status: entry[:status],
+              note: note(id),
+            }
+          end
+
+          rendered["elk.algorithm"][:values] = algorithm_values
+          rendered
+        end
+
+        private
+
+        # canonical(id) already checks OPTIONS.key?(key_str) as its very
+        # first step, so when it returns nil, OPTIONS[id.to_s] is
+        # provably nil too — no `|| id.to_s` fallback needed here.
+        def entry_for(id)
+          OPTIONS[canonical(id)]
+        end
+
+        def suffix_match(key_str)
+          matches = OPTIONS.keys.select { |id| id.end_with?(".#{key_str}") }
+          matches.first if matches.size == 1
+        end
+
+        def coerce_typed(type, value, entry, id)
+          case type
+          when :float then value.to_f
+          when :integer then value.to_i
+          when :string then value.to_s
+          when :boolean then coerce_boolean(value)
+          when :enum then coerce_enum(value, entry, id)
+          when :padding then coerce_padding(value, entry[:default])
+          when :kvector then Options::KVector.parse(value)
+          when :kvector_chain then Options::KVectorChain.parse(value)
+          else value
+          end
+        end
+
+        def coerce_enum(value, entry, id)
+          normalized = value.to_s.upcase
+          normalized = entry.fetch(:value_aliases, {}).fetch(
+            normalized, normalized
+          )
+          allowed = entry[:accepted_values] || entry[:values]
+          return normalized if allowed.include?(normalized)
+
+          raise Elkrb::ValidationError,
+                "Invalid value for #{id}: #{normalized}; " \
+                "allowed values: #{allowed.join(', ')}"
+        end
+
+        # Strict boolean-env semantics: only true itself, or the literal
+        # string "true" (case-insensitive), coerces to true. "1", "yes",
+        # and everything else — including malformed input — coerce to
+        # false; no numeric or word aliases for "true" are recognised.
+        def coerce_boolean(value)
+          # `value` stays the receiver so a delegator wrapping a boolean answers
+          # for itself and comes back unwrapped. Both rewrites rubocop offers
+          # here -- Array#include? and any?(value) -- compare the other way
+          # round, and one of them swaps == for ===, so neither is equivalent.
+          # rubocop:disable Performance/RedundantEqualityComparisonBlock
+          return value if BOOLEAN_LITERALS.any? { |literal| value == literal }
+          # rubocop:enable Performance/RedundantEqualityComparisonBlock
+
+          value.to_s.strip.casecmp("true").zero?
+        end
+
+        def coerce_padding(value, default_string)
+          return value if value.is_a?(ElkPadding)
+          return ElkPadding.parse(value) if value.is_a?(String)
+
+          if value.is_a?(Numeric)
+            return ElkPadding.new(top: value, left: value, bottom: value,
+                                  right: value)
+          end
+
+          unless value.is_a?(Hash)
+            raise ArgumentError,
+                  "Invalid padding value: #{value.inspect}"
+          end
+
+          fallback = ElkPadding.parse(default_string)
+          ElkPadding.new(
+            **fallback.to_h.to_h do |side, default|
+              [side, Decimal.component(value, side, default)]
+            end,
+          )
+        end
+      end
+    end
+  end
+end