sevgi-graphics 0.94.0 → 0.98.2

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
@@ -53,20 +55,16 @@ module Sevgi
         # @return [Sevgi::Graphics::Element] self
         # @raise [Sevgi::ArgumentError] when the target parent has a different element class
         # @raise [Sevgi::ArgumentError] when the target parent is this element or one of its descendants
+        # @raise [Sevgi::ArgumentError] when index is not an Integer insertion position
         def Adopt(new_parent = nil, index: -1)
           tap do
-            if new_parent
-              unless instance_of?(new_parent.class)
-                ArgumentError.("Element type does not match the new parent type: #{self.class}")
-              end
-            else
-              new_parent = parent
-            end
-
+            new_parent ||= parent
             Adoption.validate(self, new_parent)
 
+            insertion = Adoption.index_for(self, new_parent, index)
+
             self.Orphan()
-            (@parent = new_parent).children.insert(index, self)
+            Element.send(:attach, self, new_parent, index: insertion)
           end
         end
 
@@ -80,11 +78,19 @@ module Sevgi
           Adopt(*, index: 0)
         end
 
-        # Appends existing elements as children.
-        # @param elements [Array<Sevgi::Graphics::Element>] elements to append
+        # 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
         def Append(*elements)
-          tap { elements.each { it.Adopt(self) } }
+          tap { Adoption.batch(elements, self, front: false) }
         end
 
         # Adds CSS classes without duplicating existing values.
@@ -124,9 +130,13 @@ module Sevgi
         # @param tag [Symbol, String] SVG tag name
         # @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.to_sym, 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.
@@ -147,24 +157,30 @@ module Sevgi
           self.name() == name.to_sym
         end
 
-        # Removes this element from its parent.
-        # @return [Array<Sevgi::Graphics::Element>, nil] parent children after deletion, 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 existing elements as children.
-        # @param elements [Array<Sevgi::Graphics::Element>] elements to prepend
+        # Prepends distinct existing elements as children in argument order.
+        # Each element transfers from its current parent. The complete batch is validated before any element moves.
+        # @param elements [Array<Sevgi::Graphics::Element>] distinct elements to prepend
         # @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
         def Prepend(*elements)
-          tap { elements.each { it.AdoptFirst(self) } }
+          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
@@ -172,18 +188,26 @@ 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
+        # @yieldparam element [Sevgi::Graphics::Element] visited element
+        # @yieldparam depth [Integer] element depth
+        # @yieldreturn [Object] ignored unless it is a {Stop} token
         # @return [Sevgi::Graphics::Element, Object] self or the value passed through Stay
         # @raise [Sevgi::ArgumentError] when no block is given
         def Traverse(depth = 0, leave = nil, &block)
@@ -194,6 +218,10 @@ module Sevgi
 
         # Traverses ancestors from this element to the root.
         # @param height [Integer] starting height
+        # @yield [element, height] visits this element and each ancestor
+        # @yieldparam element [Sevgi::Graphics::Element] visited element
+        # @yieldparam height [Integer] ancestor height
+        # @yieldreturn [Object] ignored unless it is a {Stop} token
         # @return [Object, nil] value passed through Stay, or nil
         # @raise [Sevgi::ArgumentError] when no block is given
         def TraverseUp(height = 0, &block)
@@ -204,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
@@ -212,24 +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 [*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 [*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 would create a tree cycle
         def <<(element)
           Append(element)
         end
@@ -237,12 +291,32 @@ module Sevgi
         # Adoption target validation that keeps tree mutation atomic.
         # @api private
         module Adoption
+          # Moves a validated batch to the front or back of a parent.
+          # @param elements [Array<Sevgi::Graphics::Element>] elements to move
+          # @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
+          def self.batch(elements, parent, front:)
+            validate_batch(elements, parent)
+
+            if front
+              elements.reverse_each { it.AdoptFirst(parent) }
+            else
+              elements.each { it.Adopt(parent) }
+            end
+          end
+
           # Rejects target parents that would 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 target parent is this element or one of its descendants
+          # @raise [Sevgi::ArgumentError] when the parent is incompatible or would create 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}")
+            end
+
             ArgumentError.("Element cannot be adopted under itself") if parent.equal?(element)
 
             while parent.respond_to?(:Root?)
@@ -252,6 +326,42 @@ module Sevgi
               parent = parent.parent
             end
           end
+
+          # Normalizes an insertion index before tree mutation.
+          # @param index [Integer] requested insertion index
+          # @param size [Integer] number of available child positions
+          # @return [Integer] normalized non-negative insertion index
+          # @raise [Sevgi::ArgumentError] when the index is not an insertion position
+          def self.index(index, size)
+            ArgumentError.("Adoption index must be an Integer") unless index.is_a?(Integer)
+
+            normalized = index.negative? ? size + index + 1 : index
+            ArgumentError.("Adoption index is outside the child list") unless normalized.between?(0, size)
+
+            normalized
+          end
+
+          # Returns an insertion index after accounting for a same-parent move.
+          # @param element [Sevgi::Graphics::Element] element being moved
+          # @param parent [Sevgi::Graphics::Element] target parent
+          # @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))
+          end
+
+          def self.validate_batch(elements, parent)
+            seen = {}.compare_by_identity
+            elements.each do |element|
+              ArgumentError.("Element appears more than once in adoption batch") if seen.key?(element)
+
+              seen[element] = true
+              validate(element, parent)
+            end
+          end
+
+          private_class_method :validate_batch
         end
 
         private_constant :Adoption

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

@@ -6,30 +6,31 @@ 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.
+        # @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)
+          dx, dy, target = Subtree.channels(self, dx, dy, parent)
           duplicated = Subtree.copy(self)
-
-          duplicated.Traverse() do |element|
-            id = element.attributes.delete(:id)
-            element[:"#{ATTRIBUTE_INTERNAL_PREFIX}id"] = id if id
-            block&.call(element)
-          end
-
-          duplicated.Translate(dx, dy) if dx || dy
-
-          duplicated.Adopt(parent)
-
-          duplicated
+          Subtree.prepare(duplicated, &block)
+          Subtree.translate(duplicated, dx, dy)
+          Subtree.attach(duplicated, target)
         end
 
         # Duplicates an element subtree along the x-axis.
@@ -37,34 +38,87 @@ module Sevgi
         # @param parent [Sevgi::Graphics::Element, nil] parent for the duplicated subtree
         # @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
-        def DuplicateX(dx, parent: nil, &block) = Duplicate(dx:, dy: 0, parent:, &block)
+        # @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)
+          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
         # @param parent [Sevgi::Graphics::Element, nil] parent for the duplicated subtree
         # @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
-        def DuplicateY(dy, parent: nil, &block) = Duplicate(dx: 0, dy:, parent:, &block)
+        # @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)
+          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
+          # 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
+
           # 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)
+          def self.copy(element, parent = Element.send(:tree_parent, element))
             element.dup.tap do |duplicated|
               duplicated.send(:parent=, parent)
               duplicated.send(:attributes=, element.attributes.dup)
-              duplicated.send(:contents=, element.contents.dup)
+              duplicated.send(:contents=, element.contents.map(&:dup))
               duplicated.send(:children=, element.children.map { |child| copy(child, duplicated) })
             end
           end
+
+          # Removes copied public ids and applies an optional customization hook.
+          # @api private
+          def self.prepare(element, &block)
+            element.Traverse() do |node|
+              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
+
+          # Applies an optional translation to a copied subtree.
+          # @api private
+          def self.translate(element, 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, target)
+            element.Adopt(target) if target
+            element
+          end
         end
 
         private_constant :Subtree

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

@@ -5,14 +5,48 @@ module Sevgi
     module Mixtures
       # DSL helpers for native SVG export formats.
       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
-        # @return [String] output path
+        # @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] 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"
 
@@ -26,13 +60,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
-        # @return [String] output path
+        # @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] 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"
 
@@ -48,15 +97,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 lined 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::Lined] lined 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::Lined)
+          Draw(Geometry::Operation.sweep!(element, initial:, angle:, step:), **kwargs)
         end
       end
     end