sevgi-graphics 0.95.0 → 1.0.0

data/lib/sevgi/graphics/mixtures/core.rb

@@ -9,7 +9,9 @@ module Sevgi
       #
       # @!attribute [r] value
       #   @return [Object] value returned from traversal
-      Stop = Data.define(:value)
+      Stop = Data.define(:value) do
+        private_class_method :[], :new
+      end
 
       # Internal traversal engine.
       # @api private
@@ -62,7 +64,7 @@ module Sevgi
             insertion = Adoption.index_for(self, new_parent, index)
 
             self.Orphan()
-            (@parent = new_parent).children.insert(insertion, self)
+            Element.send(:attach, self, new_parent, index: insertion)
           end
         end
 
@@ -78,6 +80,12 @@ module Sevgi
 
         # Appends distinct existing elements as children in argument order.
         # Each element transfers from its current parent. The complete batch is validated before any element moves.
+        # @example Move existing elements into a group
+        #   Sevgi::Graphics.SVG(:minimal) do
+        #     dot = circle r: 2
+        #     label = text "Ready", x: 6
+        #     g(id: "status").Append(dot, label)
+        #   end
         # @param elements [Array<Sevgi::Graphics::Element>] distinct elements to append
         # @return [Sevgi::Graphics::Element] self
         # @raise [Sevgi::ArgumentError] when an argument has a different element class, is repeated, or is this target or its ancestor
@@ -86,7 +94,7 @@ module Sevgi
         end
 
         # Adds CSS classes without duplicating existing values.
-        # @param classes [Array<String, Symbol, Array>] class tokens; strings are split on whitespace
+        # @param classes [Array<String, Symbol, Array>] class tokens. Strings are split on whitespace
         # @return [Sevgi::Graphics::Element] self
         def Classify(*classes)
           tap do
@@ -120,14 +128,15 @@ module Sevgi
 
         # Builds a child element with an explicit tag name.
         # @param tag [Symbol, String] SVG tag name
-        # @param contents [Array<Object>] text or content objects; non-content objects are stringified and XML-encoded
+        # @param contents [Array<Object>] text or content objects. Non-content objects are stringified and XML-encoded
         # @param attributes [Hash] SVG attributes
         # @yield evaluates the drawing DSL in the new child element
         # @yieldreturn [Object] ignored block result
         # @return [Sevgi::Graphics::Element] new child element
         # @raise [Sevgi::ArgumentError] when the tag, attributes, or content are not valid XML
         def Element(tag, *contents, **attributes, &block)
-          self.class.send(:new, tag, contents: Content.contents(*contents), attributes:, parent: self, &block)
+          contents.map! { it.is_a?(Content) ? it : Content.encoded(it) }
+          self.class.send(:new, tag, contents:, attributes:, parent: self, &block)
         end
 
         # Forwards this element as the first argument to another receiver.
@@ -148,10 +157,13 @@ module Sevgi
           self.name() == name.to_sym
         end
 
-        # Removes this element from its parent.
-        # @return [Sevgi::Graphics::Element, nil] the deleted element, or nil for root elements
+        # Removes this element from its parent and makes it a detached subtree root.
+        # @return [Sevgi::Graphics::Element, nil] self, or nil for root elements
         def Orphan
-          parent.children&.delete(self) unless Root?()
+          return if Root?()
+
+          Element.send(:detach, self)
+          self
         end
 
         # Prepends distinct existing elements as children in argument order.
@@ -163,11 +175,12 @@ module Sevgi
           tap { Adoption.batch(elements, self, front: true) }
         end
 
-        # Returns the root document element.
-        # @return [Sevgi::Graphics::Element]
+        # Returns the topmost element in this tree.
+        # A detached subtree returns its detached topmost element. Use {#Root?} to distinguish a document root.
+        # @return [Sevgi::Graphics::Element] document root or detached topmost element
         def Root
           element = self
-          element = element.parent until element.Root?()
+          element = element.parent while element.parent
 
           element
         end
@@ -175,16 +188,20 @@ module Sevgi
         # Reports whether this element is the root document element.
         # @return [Boolean]
         def Root?
-          self.class.root?(self)
+          Element.root?(self)
         end
 
         # @overload Stay(value)
         #   Wraps a traversal return value as a stop token.
         #   @param value [Object] value returned from traversal
         #   @return [Sevgi::Graphics::Mixtures::Stop]
-        def Stay(...) = Stop.new(...)
+        def Stay(...) = Stop.send(:new, ...)
 
         # Traverses the subtree depth-first.
+        # @example Find the first circle and stop the traversal
+        #   drawing = Sevgi::Graphics.SVG(:minimal) { g { circle id: "target"; circle id: "later" } }
+        #   found = drawing.Traverse { |node| node.Stay(node) if node.Is? :circle }
+        #   found[:id] # => "target"
         # @param depth [Integer] starting depth
         # @param leave [Proc, nil] optional leave callback
         # @yield [element, depth] visits each element before its children
@@ -215,7 +232,7 @@ module Sevgi
           loop do
             yield(element, height).tap { return it.value if it.is_a?(Stop) }
 
-            break if element.Root?()
+            break unless element.parent
 
             element = element.parent
             height += 1
@@ -223,28 +240,50 @@ module Sevgi
         end
 
         # Evaluates a block in the parent element context.
-        # @param args [Array<Object>] optional receiver override followed by block arguments
+        # @example Add a sibling while forwarding its id
+        #   root = Sevgi::Graphics.SVG id: "root"
+        #   child = root.g id: "child"
+        #   child.With("sibling") { |id| line id: }
+        # @param args [Array<Object>] positional arguments passed to the block
+        # @param receiver [Sevgi::Graphics::Element] element whose parent becomes the block receiver
         # @param kwargs [Hash] keyword arguments passed to the block
-        # @yield evaluates in the selected receiver's parent context
+        # @yield [*args, **kwargs] evaluates in the selected element's parent context
         # @yieldreturn [Object] ignored block result
         # @return [Sevgi::Graphics::Element] self
-        def With(*args, **kwargs, &block)
-          tap { (args.shift || self).parent.instance_exec(*args, **kwargs, &block) }
+        # @raise [Sevgi::ArgumentError] when no block is given
+        # @raise [Sevgi::ArgumentError] when receiver is not an element or has no parent
+        def With(*args, receiver: self, **kwargs, &block)
+          ArgumentError.("Block required") unless block
+          ArgumentError.("Receiver must be an element") unless receiver.is_a?(Element)
+
+          parent = receiver.parent
+          ArgumentError.("Receiver has no parent") unless parent
+
+          tap { parent.instance_exec(*args, **kwargs, &block) }
         end
 
         # Evaluates a block in this element context.
-        # @param args [Array<Object>] optional receiver override followed by block arguments
+        # @example Select a receiver without consuming the block argument
+        #   target = Sevgi::Graphics.SVG id: "target"
+        #   source = Sevgi::Graphics.SVG id: "source"
+        #   source.Within("child", receiver: target) { |id| g id: }
+        # @param args [Array<Object>] positional arguments passed to the block
+        # @param receiver [Object] block receiver
         # @param kwargs [Hash] keyword arguments passed to the block
-        # @yield evaluates in the selected receiver context
+        # @yield [*args, **kwargs] evaluates in the selected receiver context
         # @yieldreturn [Object] ignored block result
         # @return [Sevgi::Graphics::Element] self
-        def Within(*args, **kwargs, &block)
-          tap { (args.shift || self).instance_exec(*args, **kwargs, &block) }
+        # @raise [Sevgi::ArgumentError] when no block is given
+        def Within(*args, receiver: self, **kwargs, &block)
+          ArgumentError.("Block required") unless block
+
+          tap { receiver.instance_exec(*args, **kwargs, &block) }
         end
 
         # Appends an element as a child.
         # @param element [Sevgi::Graphics::Element] element to append
         # @return [Sevgi::Graphics::Element] self
+        # @raise [Sevgi::ArgumentError] when the element has a different concrete class or creates a tree cycle
         def <<(element)
           Append(element)
         end
@@ -257,7 +296,7 @@ module Sevgi
           # @param parent [Sevgi::Graphics::Element] target parent
           # @param front [Boolean] whether to prepend instead of append
           # @return [void]
-          # @raise [Sevgi::ArgumentError] when an argument is incompatible, repeated, or would create a cycle
+          # @raise [Sevgi::ArgumentError] when an argument is incompatible, repeated, or creates a cycle
           def self.batch(elements, parent, front:)
             validate_batch(elements, parent)
 
@@ -268,11 +307,11 @@ module Sevgi
             end
           end
 
-          # Rejects target parents that would create a cycle.
+          # Rejects target parents that create a cycle.
           # @param element [Sevgi::Graphics::Element] element being moved
           # @param parent [Sevgi::Graphics::Element, Object] target parent
           # @return [void]
-          # @raise [Sevgi::ArgumentError] when the parent is incompatible or would create a cycle
+          # @raise [Sevgi::ArgumentError] when the parent is incompatible or creates a cycle
           def self.validate(element, parent)
             unless element.instance_of?(parent.class)
               ArgumentError.("Element type does not match the new parent type: #{element.class}")
@@ -308,8 +347,9 @@ module Sevgi
           # @param index [Integer] requested insertion index
           # @return [Integer] normalized insertion index
           def self.index_for(element, parent, index)
-            same_parent = element.parent.equal?(parent) && parent.children.include?(element)
-            index(index, parent.children.size - (same_parent ? 1 : 0))
+            children = Element.send(:tree_children, parent)
+            same_parent = element.parent.equal?(parent) && children.include?(element)
+            index(index, children.size - (same_parent ? 1 : 0))
           end
 
           def self.validate_batch(elements, parent)

data/lib/sevgi/graphics/mixtures/duplicate.rb

@@ -6,23 +6,32 @@ module Sevgi
       # DSL helpers for duplicating independent element subtrees.
       module Duplicate
         # Duplicates an element subtree as an independent tree and optionally translates it.
-        # Copied elements receive new child arrays, attribute stores, and content arrays. Public `id` attributes are
-        # moved to an internal `-id` attribute before the optional block runs, allowing the block to derive replacement
-        # ids without rendering duplicate public ids.
-        # @param dx [Numeric, nil] x translation
-        # @param dy [Numeric, nil] y translation
-        # @param parent [Sevgi::Graphics::Element, nil] parent for the duplicated subtree
+        # Copied elements receive new child arrays, attribute stores, and content arrays. Visible `id` attributes are
+        # moved to non-rendering `-id` metadata before the optional block runs, allowing the block to derive replacement
+        # ids without rendering duplicates. A pre-existing `-id` takes precedence over the visible id.
+        # Translation and parent channels are validated before the subtree is copied or the customization block runs.
+        # The copied subtree has no parent during customization and is attached to the target parent afterward.
+        # @param dx [Numeric, nil] finite x translation. Nil omits the axis
+        # @param dy [Numeric, nil] finite y translation. Nil omits the axis
+        # @param parent [Sevgi::Graphics::Element, nil] explicit parent, or the source parent when nil
         # @yield [element] optional customization hook for each copied element
         # @yieldparam element [Sevgi::Graphics::Element] copied element
         # @yieldreturn [Object] ignored customization result
         # @return [Sevgi::Graphics::Element] duplicated element
         # @raise [Sevgi::ArgumentError] when the target parent has a different element class
+        # @raise [Sevgi::ArgumentError] when a translation is not a finite real number
         # @raise [Sevgi::ArgumentError] when copied attributes or contents contain cyclic payloads
+        # @example Remap source ids on a duplicate
+        #   source = Sevgi::Graphics.SVG { rect id: "shape" }.children.first
+        #   copy = source.Duplicate do |node|
+        #     node[:id] = "#{node[:"-id"]}-copy" if node[:"-id"]
+        #   end
         def Duplicate(dx: nil, dy: nil, parent: nil, &block)
-          duplicated = Subtree.copy(self)
+          dx, dy, target = Subtree.channels(self, dx, dy, parent)
+          duplicated = dup
           Subtree.prepare(duplicated, &block)
           Subtree.translate(duplicated, dx, dy)
-          Subtree.attach(duplicated, self, parent)
+          Subtree.attach(duplicated, target)
         end
 
         # Duplicates an element subtree along the x-axis.
@@ -33,8 +42,12 @@ module Sevgi
         # @yieldreturn [Object] ignored customization result
         # @return [Sevgi::Graphics::Element] duplicated element
         # @raise [Sevgi::ArgumentError] when the target parent has a different element class
+        # @raise [Sevgi::ArgumentError] when dx is not a finite real number
         # @raise [Sevgi::ArgumentError] when copied attributes or contents contain cyclic payloads
-        def DuplicateX(dx, parent: nil, &block) = Duplicate(dx:, dy: 0, parent:, &block)
+        def DuplicateX(dx, parent: nil, &block)
+          ArgumentError.("Duplicate x translation cannot be nil") if dx.nil?
+          Duplicate(dx:, dy: 0, parent:, &block)
+        end
 
         # Duplicates an element subtree along the y-axis.
         # @param dy [Numeric] y translation
@@ -44,31 +57,40 @@ module Sevgi
         # @yieldreturn [Object] ignored customization result
         # @return [Sevgi::Graphics::Element] duplicated element
         # @raise [Sevgi::ArgumentError] when the target parent has a different element class
+        # @raise [Sevgi::ArgumentError] when dy is not a finite real number
         # @raise [Sevgi::ArgumentError] when copied attributes or contents contain cyclic payloads
-        def DuplicateY(dy, parent: nil, &block) = Duplicate(dx: 0, dy:, parent:, &block)
+        def DuplicateY(dy, parent: nil, &block)
+          ArgumentError.("Duplicate y translation cannot be nil") if dy.nil?
+          Duplicate(dx: 0, dy:, parent:, &block)
+        end
 
         # Recursive subtree copier that keeps duplicate implementation state out of the DSL surface.
         # @api private
         module Subtree
-          # Builds an independent copy of an element subtree.
-          # @param element [Sevgi::Graphics::Element] source subtree root
-          # @param parent [Sevgi::Graphics::Element, Object] parent for the copied root
-          # @return [Sevgi::Graphics::Element] copied subtree root
-          def self.copy(element, parent = element.parent)
-            element.dup.tap do |duplicated|
-              duplicated.send(:parent=, parent)
-              duplicated.send(:attributes=, element.attributes.dup)
-              duplicated.send(:contents=, element.contents.map(&:dup))
-              duplicated.send(:children=, element.children.map { |child| copy(child, duplicated) })
+          # Validates and normalizes duplicate option channels before copying.
+          # @return [Array<(Integer, Float, Sevgi::Graphics::Element, nil)>] normalized dx, dy, and target parent
+          # @raise [Sevgi::ArgumentError] when a translation or parent is invalid
+          def self.channels(source, dx, dy, parent)
+            target = parent.nil? ? source.parent : parent
+            unless target.nil? || source.instance_of?(target.class)
+              ArgumentError.("Element type does not match the new parent type: #{source.class}")
             end
+
+            dx = Scalar.number(dx, context: "duplicate translation", field: :x) unless dx.nil?
+            dy = Scalar.number(dy, context: "duplicate translation", field: :y) unless dy.nil?
+            [dx, dy, target]
           end
 
           # Removes copied public ids and applies an optional customization hook.
           # @api private
           def self.prepare(element, &block)
             element.Traverse() do |node|
-              id = node.attributes.delete(:id)
-              node[:"#{ATTRIBUTE_INTERNAL_PREFIX}id"] = id if id
+              if node.attributes.has?(:id)
+                id = node.attributes.delete(:id)
+                metadata = :"#{Attributes::META_PREFIX}id"
+                node[metadata] = id unless node.attributes.has?(metadata)
+              end
+
               block&.call(node)
             end
           end
@@ -76,13 +98,13 @@ module Sevgi
           # Applies an optional translation to a copied subtree.
           # @api private
           def self.translate(element, dx, dy)
-            element.Translate(dx, dy) if dx || dy
+            element.Translate(dx || 0, dy) unless dx.nil? && dy.nil?
           end
 
           # Attaches a copied subtree unless it is a detached root copy.
           # @api private
-          def self.attach(element, source, parent)
-            element.Adopt(parent) if parent || !source.Root?()
+          def self.attach(element, target)
+            element.Adopt(target) if target
             element
           end
         end

data/lib/sevgi/graphics/mixtures/export.rb

@@ -4,18 +4,51 @@ module Sevgi
   module Graphics
     module Mixtures
       # DSL helpers for native SVG export formats.
+      # Export CSS is a late adjustment after document checks. Its supported XML endings and cascade limitations are
+      # documented in {Sevgi::Sundries::Export}. The source callback receives SVG after CSS insertion.
       module Export
+        # Validates the closed export option channel before optional components load or rendering starts.
+        # @api private
+        module Options
+          KEYS = %i[css default dpi height width].freeze
+          private_constant :KEYS
+
+          # Returns validated export options.
+          # @param options [Hash] export options
+          # @return [Hash] original options
+          # @raise [Sevgi::ArgumentError] when an option is unknown
+          def self.call(options)
+            unknown = options.keys - KEYS
+            ArgumentError.("Unknown export option: #{unknown.first}") unless unknown.empty?
+            options
+          end
+        end
+
+        private_constant :Options
+
         # Exports the document as PDF.
-        # @param path [String, nil] output path or directory
+        # Relative paths are expanded, missing parent directories are created after export validation, and an existing
+        # file is replaced. An existing directory target uses the caller-derived default PDF name.
+        # @param path [String, #to_path, nil] output path or existing directory
         # @param kwargs [Hash] export options
+        # @option kwargs [String, #to_path, nil] :default caller-derived output name used when path is nil or a directory
+        # @option kwargs [Numeric, nil] :width finite positive target width in CSS pixels
+        # @option kwargs [Numeric, nil] :height finite positive target height in CSS pixels
+        # @option kwargs [Numeric] :dpi (96.0) finite positive CSS pixel density
+        # @option kwargs [String, nil] :css CSS inserted before rendering
         # @yield [svg] transforms SVG source before rendering
         # @yieldparam svg [String] rendered SVG source
         # @yieldreturn [String] transformed SVG source
-        # @return [String] output path
+        # @return [String] expanded output path
+        # @raise [Sevgi::ArgumentError] when a path, default, option name, CSS value, or transformed SVG is invalid
+        # @raise [Sevgi::ValidationError] when validation is enabled and the document violates the SVG standard
+        # @raise [Sevgi::Graphics::LintError] when linting is enabled and the document has structural conflicts
         # @raise [Sevgi::MissingComponentError] when sevgi/sundries is unavailable
         # @raise [Sevgi::MissingComponentError] when native export gems are unavailable
         # @raise [Sevgi::Sundries::Export::ExportError] when native export fails
+        # @raise [SystemCallError] when the output directory or file cannot be created or written
         def PDF(path = nil, **kwargs, &block)
+          kwargs = Options.(kwargs)
           begin
             require "sevgi/sundries"
 
@@ -29,16 +62,28 @@ module Sevgi
         end
 
         # Exports the document as PNG.
-        # @param path [String, nil] output path or directory
+        # Relative paths are expanded, missing parent directories are created after export validation, and an existing
+        # file is replaced. An existing directory target uses the caller-derived default PNG name.
+        # @param path [String, #to_path, nil] output path or existing directory
         # @param kwargs [Hash] export options
+        # @option kwargs [String, #to_path, nil] :default caller-derived output name used when path is nil or a directory
+        # @option kwargs [Numeric, nil] :width finite positive target width in output pixels
+        # @option kwargs [Numeric, nil] :height finite positive target height in output pixels
+        # @option kwargs [Numeric] :dpi (96.0) finite positive CSS pixel density
+        # @option kwargs [String, nil] :css CSS inserted before rendering
         # @yield [svg] transforms SVG source before rendering
         # @yieldparam svg [String] rendered SVG source
         # @yieldreturn [String] transformed SVG source
-        # @return [String] output path
+        # @return [String] expanded output path
+        # @raise [Sevgi::ArgumentError] when a path, default, option name, CSS value, or transformed SVG is invalid
+        # @raise [Sevgi::ValidationError] when validation is enabled and the document violates the SVG standard
+        # @raise [Sevgi::Graphics::LintError] when linting is enabled and the document has structural conflicts
         # @raise [Sevgi::MissingComponentError] when sevgi/sundries is unavailable
         # @raise [Sevgi::MissingComponentError] when native export gems are unavailable
         # @raise [Sevgi::Sundries::Export::ExportError] when native export fails
+        # @raise [SystemCallError] when the output directory or file cannot be created or written
         def PNG(path = nil, **kwargs, &block)
+          kwargs = Options.(kwargs)
           begin
             require "sevgi/sundries"
 
@@ -54,15 +99,12 @@ module Sevgi
         private
 
         def Export(path = nil, default: nil, **kwargs, &block)
-          default ||= F.subext(kwargs[:format] ? ".#{kwargs[:format]}" : ".pdf", caller_locations(2..2).first.path)
-
-          if path
-            ::File.directory?(path) ? ::File.join(path, ::File.basename(default)) : path
-          else
-            default
-          end => path
+          if default.nil?
+            extension = kwargs[:format] ? ".#{kwargs[:format]}" : ".pdf"
+            default = F.subext(extension, caller_locations(2..2).first.path)
+          end
 
-          ::FileUtils.mkdir_p(::File.dirname(path))
+          path = Path.resolve(path, default:, context: "Export")
 
           Sundries::Export.(call, path, **kwargs, &block)
         end

data/lib/sevgi/graphics/mixtures/hatch.rb

@@ -3,24 +3,65 @@
 module Sevgi
   module Graphics
     module Mixtures
-      # DSL helpers for drawing geometry-derived hatch lines.
+      # DSL helpers for drawing geometry values and geometry-derived hatch lines.
+      #
+      # `Draw` delegates to each geometry object's drawing protocol. `Hatch`
+      # first sweeps interior spans through a closed geometry element, then draws
+      # them. Its `angle` describes line direction. `step` is perpendicular
+      # spacing. The default initial line passes through `element.position`.
+      # The built-in `:inkscape` document profile includes this mixture.
+      # `:minimal`, `:default`, and `:html` do not.
+      #
+      # Hatch materializes separate finite SVG path elements. When only a repeated visual fill matters, use an SVG
+      # pattern and leave repetition and clipping to the renderer instead of computing line geometry.
+      # @example Add geometry drawing to a scoped custom profile
+      #   profile = Class.new(Sevgi::Graphics::Document::Base)
+      #   Sevgi::Graphics::Mixtures.mixin(:Hatch, profile)
+      #   region = Sevgi::Geometry::Rect[24, 12]
+      #   Sevgi::Graphics.SVG(profile) do
+      #     Draw region.lines, stroke: "silver"
+      #     Hatch region, angle: 30, step: 3, stroke: "black"
+      #   end.Render
+      # @see Sevgi::Geometry::Operation.sweep
+      # @see https://developer.mozilla.org/en-US/docs/Web/SVG/Reference/Element/pattern SVG pattern element
       module Hatch
         # Draws one or more geometry line-like objects into this element.
-        # @param lines [Object, Array<Object>] drawable geometry objects
+        # @example Draw geometry lines into a library-built document
+        #   lines = [
+        #     Sevgi::Geometry::Line.([0, 0], [20, 0]),
+        #     Sevgi::Geometry::Line.([0, 5], [20, 5])
+        #   ]
+        #   drawing = Sevgi::Graphics.SVG(:inkscape) { Draw lines, stroke: "silver" }
+        #   drawing.Render
+        # @param lines [#draw, Array<#draw>] drawable geometry objects
         # @param kwargs [Hash] SVG attributes passed to each draw call
-        # @return [Array<Sevgi::Graphics::Element>] rendered line elements
+        # @return [Array<Sevgi::Graphics::Element>] rendered SVG elements
         def Draw(lines, **kwargs)
           Array(lines).map { it.draw(self, **kwargs) }
         end
 
         # Draws hatch lines swept through a geometry element.
-        # @param element [Object] geometry element responding to position
+        # @example Hatch a closed geometry shape
+        #   region = Sevgi::Geometry::Rect[24, 12, position: [2, 2]]
+        #   drawing = Sevgi::Graphics.SVG(:inkscape) do
+        #     Hatch region, angle: 30, step: 3, stroke: "black"
+        #   end
+        #   drawing.Render
+        # @example Control the first sweep line explicitly
+        #   region = Sevgi::Geometry::Rect[24, 12, position: [2, 2]]
+        #   Sevgi::Graphics.SVG(:inkscape) do
+        #     Hatch region, initial: [2, 8], angle: 0, step: 3
+        #   end
+        # @param element [Sevgi::Geometry::Element] geometry element to sweep
         # @param angle [Numeric] hatch angle in degrees
         # @param step [Numeric] distance between hatch lines
-        # @param initial [Object, nil] initial point for the sweep
+        # @param initial [Sevgi::Geometry::Point, Array<Numeric>, nil] initial sweep point, or nil for element.position
         # @param kwargs [Hash] SVG attributes passed to each draw call
-        # @return [Array<Sevgi::Graphics::Element>] rendered line elements
+        # @return [Array<Sevgi::Graphics::Element>] rendered hatch path elements
         # @raise [Sevgi::MissingComponentError] when sevgi/geometry is unavailable
+        # @raise [Sevgi::Geometry::Operation::OperationInapplicableError] when element is not sweepable
+        # @raise [Sevgi::Geometry::Error] when initial, angle, or step is invalid
+        # @raise [Sevgi::Geometry::Operation::OperationError] when no hatch lines are found or iteration reaches the limit
         def Hatch(element, angle:, step:, initial: nil, **kwargs)
           begin
             require "sevgi/geometry"
@@ -31,7 +72,8 @@ module Sevgi
             MissingComponentError.("sevgi/geometry")
           end
 
-          Draw(Geometry::Operation.sweep!(element, initial: initial || element.position, angle:, step:), **kwargs)
+          initial = element.position if initial.nil? && element.is_a?(Geometry::Element)
+          Draw(Geometry::Operation.sweep!(element, initial:, angle:, step:), **kwargs)
         end
       end
     end

data/lib/sevgi/graphics/mixtures/identify.rb

@@ -5,15 +5,17 @@ module Sevgi
     module Mixtures
       # DSL helpers for collecting and hiding SVG ids.
       module Identify
-        # Index of element ids under a subtree.
+        # Immutable snapshot of every rendered element id under a subtree. Keys are the serialized id values, including
+        # `"false"` and the empty String. Keys and containers are owned by the index. Values retain references to the
+        # elements present when the snapshot is built. Later tree changes require a new index.
         class Identifiers
           # @return [Sevgi::Graphics::Element] indexed root element
           attr_reader :element
 
-          # @return [Hash<String, Sevgi::Graphics::Element>] id namespace
+          # @return [Hash<String, Sevgi::Graphics::Element>] frozen namespace keyed by serialized rendered ids
           attr_reader :namespace
 
-          # @return [Hash<String, Array<Sevgi::Graphics::Element>>] duplicate id groups
+          # @return [Hash<String, Array<Sevgi::Graphics::Element>>] frozen duplicate groups keyed by serialized ids
           attr_reader :collision
 
           # Builds an id index for an element subtree.
@@ -25,6 +27,10 @@ module Sevgi
             @collision = {}
 
             build
+            @namespace.freeze
+            @collision.each_value(&:freeze)
+            @collision.freeze
+            freeze
           end
 
           # Reports whether duplicate ids were found.
@@ -33,21 +39,20 @@ module Sevgi
             !@collision.empty?
           end
 
-          # @overload [](id)
-          #   Returns the element registered for an id.
-          #   @param id [String] SVG id
-          #   @return [Sevgi::Graphics::Element, nil]
-          def [](*)
-            @namespace[*]
-          end
+          # Returns the first element registered for an id in the snapshot.
+          # Duplicate entries are available through {#collision}.
+          # @param id [String] serialized rendered SVG id
+          # @return [Sevgi::Graphics::Element, nil]
+          def [](id) = @namespace[id]
 
           private
 
           def build
             element.Traverse() do |element|
-              next unless (value = element[:id])
+              next unless element.attributes.has?(:id)
 
-              id = Attribute.xml_text(value)
+              value = element[:id]
+              id = Attribute.xml_text(value).dup.freeze
 
               if @namespace.key?(id)
                 (@collision[id] ||= [@namespace[id]]) << element
@@ -58,18 +63,26 @@ module Sevgi
           end
         end
 
-        # Moves visible id attributes to Sevgi-internal id storage.
+        # Moves visible id attributes to non-rendering `-id` metadata throughout the subtree.
+        # A pre-existing `-id` takes precedence over the visible id.
         # @return [Sevgi::Graphics::Element] self
+        # @example Hide ids while retaining their source identity
+        #   document = Sevgi::Graphics.SVG { rect id: "source-id" }
+        #   document.Disidentify
+        #   document.children.first[:"-id"] # => "source-id"
         def Disidentify
           Traverse do |element|
-            next unless element[:id]
+            next unless element.attributes.has?(:id)
 
-            element[:"#{ATTRIBUTE_INTERNAL_PREFIX}id"] = element.attributes.delete(:id)
+            id = element.attributes.delete(:id)
+            metadata = :"#{Attributes::META_PREFIX}id"
+            element[metadata] = id unless element.attributes.has?(metadata)
           end
         end
 
-        # Builds an id index for this element subtree.
-        # @return [Sevgi::Graphics::Mixtures::Identify::Identifiers]
+        # Builds an immutable id index snapshot for the current element subtree.
+        # Rebuild the index to observe later id or tree changes.
+        # @return [Sevgi::Graphics::Mixtures::Identify::Identifiers] new snapshot retaining indexed element references
         def Identifiers = Identifiers.new(self)
       end
     end