sevgi-graphics 0.94.0 → 0.95.0

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

@@ -53,20 +53,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)
+            (@parent = new_parent).children.insert(insertion, self)
           end
         end
 
@@ -80,11 +76,13 @@ 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.
+        # @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 +122,12 @@ 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)
+          self.class.send(:new, tag, contents: Content.contents(*contents), attributes:, parent: self, &block)
         end
 
         # Forwards this element as the first argument to another receiver.
@@ -148,16 +149,18 @@ module Sevgi
         end
 
         # Removes this element from its parent.
-        # @return [Array<Sevgi::Graphics::Element>, nil] parent children after deletion, or nil for root elements
+        # @return [Sevgi::Graphics::Element, nil] the deleted element, or nil for root elements
         def Orphan
           parent.children&.delete(self) unless Root?()
         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.
@@ -184,6 +187,10 @@ module Sevgi
         # Traverses the subtree depth-first.
         # @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 +201,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)
@@ -214,6 +225,8 @@ module Sevgi
         # Evaluates a block in the parent element context.
         # @param args [Array<Object>] optional receiver override followed by block arguments
         # @param kwargs [Hash] keyword arguments passed to the block
+        # @yield evaluates in the selected receiver'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) }
@@ -222,6 +235,8 @@ module Sevgi
         # Evaluates a block in this element context.
         # @param args [Array<Object>] optional receiver override followed by block arguments
         # @param kwargs [Hash] keyword arguments passed to the block
+        # @yield 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) }
@@ -237,12 +252,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 +287,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

@@ -14,22 +14,15 @@ 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
+        # @raise [Sevgi::ArgumentError] when copied attributes or contents contain cyclic payloads
         def Duplicate(dx: nil, dy: nil, parent: nil, &block)
           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, self, parent)
         end
 
         # Duplicates an element subtree along the x-axis.
@@ -37,8 +30,10 @@ 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
+        # @raise [Sevgi::ArgumentError] when copied attributes or contents contain cyclic payloads
         def DuplicateX(dx, parent: nil, &block) = Duplicate(dx:, dy: 0, parent:, &block)
 
         # Duplicates an element subtree along the y-axis.
@@ -46,8 +41,10 @@ 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
+        # @raise [Sevgi::ArgumentError] when copied attributes or contents contain cyclic payloads
         def DuplicateY(dy, parent: nil, &block) = Duplicate(dx: 0, dy:, parent:, &block)
 
         # Recursive subtree copier that keeps duplicate implementation state out of the DSL surface.
@@ -61,10 +58,33 @@ module Sevgi
             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|
+              id = node.attributes.delete(:id)
+              node[:"#{ATTRIBUTE_INTERNAL_PREFIX}id"] = id if id
+              block&.call(node)
+            end
+          end
+
+          # Applies an optional translation to a copied subtree.
+          # @api private
+          def self.translate(element, dx, dy)
+            element.Translate(dx, dy) if dx || dy
+          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?()
+            element
+          end
         end
 
         private_constant :Subtree

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

@@ -8,6 +8,9 @@ module Sevgi
         # Exports the document as PDF.
         # @param path [String, nil] output path or directory
         # @param kwargs [Hash] export options
+        # @yield [svg] transforms SVG source before rendering
+        # @yieldparam svg [String] rendered SVG source
+        # @yieldreturn [String] transformed SVG source
         # @return [String] output path
         # @raise [Sevgi::MissingComponentError] when sevgi/sundries is unavailable
         # @raise [Sevgi::MissingComponentError] when native export gems are unavailable
@@ -28,6 +31,9 @@ module Sevgi
         # Exports the document as PNG.
         # @param path [String, nil] output path or directory
         # @param kwargs [Hash] export options
+        # @yield [svg] transforms SVG source before rendering
+        # @yieldparam svg [String] rendered SVG source
+        # @yieldreturn [String] transformed SVG source
         # @return [String] output path
         # @raise [Sevgi::MissingComponentError] when sevgi/sundries is unavailable
         # @raise [Sevgi::MissingComponentError] when native export gems are unavailable

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

@@ -4,6 +4,23 @@ module Sevgi
   module Graphics
     module Mixtures
       # DSL helpers for including derendered SVG/XML fragments.
+      #
+      # @!method Include(file, id)
+      #   Includes a derendered node matching an id.
+      #   SVG/XML content is treated as data and is not evaluated as Ruby source.
+      #   @param file [String] source SVG/XML file
+      #   @param id [String, Symbol] source node id
+      #   @return [Sevgi::Graphics::Element, nil] included element, or nil when it produces no graphics output
+      #   @raise [Sevgi::ArgumentError] when the file is absent or XML content is malformed, rootless, or lacks the id
+      #   @raise [Sevgi::MissingComponentError] when sevgi/derender is unavailable
+      # @!method IncludeChildren(file, id)
+      #   Includes the children of a derendered node matching an id.
+      #   SVG/XML content is treated as data and is not evaluated as Ruby source.
+      #   @param file [String] source SVG/XML file
+      #   @param id [String, Symbol] source node id
+      #   @return [Array<Sevgi::Graphics::Element>] included children
+      #   @raise [Sevgi::ArgumentError] when the file is absent or XML content is malformed, rootless, or lacks the id
+      #   @raise [Sevgi::MissingComponentError] when sevgi/derender is unavailable
       module Include
         require "sevgi/derender"
 

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

@@ -26,6 +26,8 @@ module Sevgi
         # @param mod [Module] callable drawing module
         # @param args [Array<Object>] callable arguments
         # @param kwargs [Hash] group attributes
+        # @yield forwards customization to the callable module
+        # @yieldreturn [Object] callable customization result
         # @return [Sevgi::Graphics::Element] group element
         # @raise [Sevgi::ArgumentError] when mod is not a plain module
         def Group(mod, *args, **kwargs, &block)
@@ -37,6 +39,8 @@ module Sevgi
         # @param mod [Module] callable drawing module
         # @param args [Array<Object>] callable arguments
         # @param kwargs [Hash] layer attributes
+        # @yield forwards customization to the callable module
+        # @yieldreturn [Object] callable customization result
         # @return [Sevgi::Graphics::Element] layer element
         # @raise [Sevgi::ArgumentError] when mod is not a plain module
         def Layer(mod, *args, **kwargs, &block)
@@ -48,6 +52,8 @@ module Sevgi
         # @param mod [Module] callable drawing module
         # @param args [Array<Object>] callable arguments
         # @param kwargs [Hash] layer attributes
+        # @yield forwards customization to the callable module
+        # @yieldreturn [Object] callable customization result
         # @return [Sevgi::Graphics::Element] layer element
         # @raise [Sevgi::ArgumentError] when mod is not a plain module
         def Layer!(mod, *args, **kwargs, &block)
@@ -58,6 +64,8 @@ module Sevgi
         # @overload layer(**attributes)
         #   Builds an Inkscape layer group.
         #   @param attributes [Hash] layer attributes
+        #   @yield evaluates the drawing DSL in the layer
+        #   @yieldreturn [Object] ignored block result
         #   @return [Sevgi::Graphics::Element] layer group
         def layer(**, &block)
           g("inkscape:groupmode": "layer", **, &block)
@@ -66,6 +74,8 @@ module Sevgi
         # @overload layer!(**attributes)
         #   Builds an insensitive Inkscape layer group.
         #   @param attributes [Hash] layer attributes
+        #   @yield evaluates the drawing DSL in the layer
+        #   @yieldreturn [Object] ignored block result
         #   @return [Sevgi::Graphics::Element] layer group
         def layer!(**, &block)
           layer("sodipodi:insensitive": "true", **, &block)
@@ -74,6 +84,9 @@ module Sevgi
         # Builds an Inkscape namedview containing page elements.
         # @param pages [Array<Hash>] page attribute hashes
         # @param id [String] namedview id
+        # @yield [page] customizes each generated page element
+        # @yieldparam page [Sevgi::Graphics::Element] generated page element
+        # @yieldreturn [Object] ignored customization result
         # @return [Sevgi::Graphics::Element] namedview element
         def Pages(*pages, id: "namedview", **, &block)
           Element(:"sodipodi:namedview", id:, **) do
@@ -111,6 +124,8 @@ module Sevgi
         # @overload symbol!(**attributes)
         #   Builds an Inkscape symbol group hidden from the symbols menu.
         #   @param attributes [Hash] symbol attributes
+        #   @yield evaluates the drawing DSL in the symbol group
+        #   @yieldreturn [Object] ignored block result
         #   @return [Sevgi::Graphics::Element] symbol group
         def symbol!(**, &block)
           if Is?(:defs)

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

@@ -7,6 +7,8 @@ module Sevgi
       module RDF
         # Adds RDF license metadata inside a metadata element.
         # @param kwargs [Hash] RDF work options
+        # @yield evaluates additional RDF work metadata
+        # @yieldreturn [Object] ignored block result
         # @return [Sevgi::Graphics::Element] metadata element
         def License(**kwargs, &block) = metadata { RDFWork(**kwargs, &block) }
 
@@ -14,6 +16,8 @@ module Sevgi
         #
         # Adds Creative Commons BY-SA license metadata.
         # @param kwargs [Hash] RDF work options
+        # @yield evaluates additional RDF work metadata
+        # @yieldreturn [Object] ignored block result
         # @return [Sevgi::Graphics::Element] metadata element
         def License_CC_BY_SA(**kwargs, &block)
           License(**kwargs, license: "https://creativecommons.org/licenses/by-sa/4.0/", &block)
@@ -21,6 +25,8 @@ module Sevgi
 
         # Adds Creative Commons BY-NC license metadata.
         # @param kwargs [Hash] RDF work options
+        # @yield evaluates additional RDF work metadata
+        # @yieldreturn [Object] ignored block result
         # @return [Sevgi::Graphics::Element] metadata element
         def License_CC_BY_NC(**kwargs, &block)
           License(**kwargs, license: "https://creativecommons.org/licenses/by-nc/4.0/", &block)
@@ -28,6 +34,8 @@ module Sevgi
 
         # Adds Creative Commons BY-NC-SA license metadata.
         # @param kwargs [Hash] RDF work options
+        # @yield evaluates additional RDF work metadata
+        # @yieldreturn [Object] ignored block result
         # @return [Sevgi::Graphics::Element] metadata element
         def License_CC_BY_NC_SA(**kwargs, &block)
           License(**kwargs, license: "https://creativecommons.org/licenses/by-nc-sa/4.0/", &block)
@@ -35,6 +43,8 @@ module Sevgi
 
         # Adds Creative Commons BY-ND license metadata.
         # @param kwargs [Hash] RDF work options
+        # @yield evaluates additional RDF work metadata
+        # @yieldreturn [Object] ignored block result
         # @return [Sevgi::Graphics::Element] metadata element
         def License_CC_BY_ND(**kwargs, &block)
           License(**kwargs, license: "https://creativecommons.org/licenses/by-nd/4.0/", &block)
@@ -42,6 +52,8 @@ module Sevgi
 
         # Adds Creative Commons BY-NC-ND license metadata.
         # @param kwargs [Hash] RDF work options
+        # @yield evaluates additional RDF work metadata
+        # @yieldreturn [Object] ignored block result
         # @return [Sevgi::Graphics::Element] metadata element
         def License_CC_BY_NC_ND(**kwargs, &block)
           License(**kwargs, license: "https://creativecommons.org/licenses/by-nc-nd/4.0/", &block)
@@ -49,6 +61,8 @@ module Sevgi
 
         # Adds Creative Commons Zero metadata.
         # @param kwargs [Hash] RDF work options
+        # @yield evaluates additional RDF work metadata
+        # @yieldreturn [Object] ignored block result
         # @return [Sevgi::Graphics::Element] metadata element
         def License_CC0(**kwargs, &block)
           License(**kwargs, license: "https://creativecommons.org/publicdomain/zero/1.0/", &block)
@@ -56,11 +70,15 @@ module Sevgi
 
         # Adds Free Art License metadata.
         # @param kwargs [Hash] RDF work options
+        # @yield evaluates additional RDF work metadata
+        # @yieldreturn [Object] ignored block result
         # @return [Sevgi::Graphics::Element] metadata element
         def License_LAL(**kwargs, &block) = License(**kwargs, license: "https://artlibre.org/licence/lal/en/", &block)
 
         # Builds an RDF root element.
         # @param _kwargs [Hash] currently unused options
+        # @yield evaluates the RDF drawing DSL
+        # @yieldreturn [Object] ignored block result
         # @return [Sevgi::Graphics::Element] RDF element
         # @raise [Sevgi::ArgumentError] when no block is given
         def RDF(**_kwargs, &block)
@@ -86,6 +104,8 @@ module Sevgi
         # @option kwargs [String] :date date
         # @option kwargs [String] :language language
         # @option kwargs [String] :license license URL
+        # @yield evaluates additional RDF work metadata
+        # @yieldreturn [Object] ignored block result
         # @return [Sevgi::Graphics::Element] RDF element
         def RDFWork(**kwargs, &block)
           RDF do

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

@@ -10,6 +10,7 @@ module Sevgi
         class Renderer
           # Default renderer options.
           DEFAULTS = {indent: "  ", linelength: 140, style: :hybrid}.freeze
+          SVG_NAMESPACE = "http://www.w3.org/2000/svg"
 
           # Attribute rendering strategies.
           # @api private
@@ -77,7 +78,7 @@ module Sevgi
           ELEMENTS_WITH_BLOCK_CONTENT = %i[style].freeze
           SEPARATOR = "\n"
 
-          private_constant :ELEMENTS_WITH_INLINE_CONTENT, :ELEMENTS_WITH_BLOCK_CONTENT, :SEPARATOR
+          private_constant :ELEMENTS_WITH_INLINE_CONTENT, :ELEMENTS_WITH_BLOCK_CONTENT, :SEPARATOR, :SVG_NAMESPACE
 
           # @return [Sevgi::Graphics::Element] root element
           attr_reader :root
@@ -161,7 +162,7 @@ module Sevgi
           #   @option options [Integer] :linelength hybrid attribute line length
           #   @option options [Symbol] :style attribute style, one of :hybrid, :inline, or :block
           #   @return [void]
-          #   @raise [Sevgi::ArgumentError] when style is missing or unsupported
+          #   @raise [Sevgi::ArgumentError] when an option is unknown, malformed, missing, or unsupported
           def initialize(root, **)
             @root = root
             @options = DEFAULTS.merge(**)
@@ -176,14 +177,14 @@ module Sevgi
           #   @param root [Sevgi::Graphics::Element] root element
           #   @param options [Hash] renderer options
           #   @return [String] SVG source
-          #   @raise [Sevgi::ArgumentError] when style is missing or unsupported
+          #   @raise [Sevgi::ArgumentError] when options, preambles, names, attributes, or content are invalid XML
           def self.call(root, **) = new(root, **).call(*root.class.preambles)
 
           # Renders a root element without document preambles.
           # @param root [Sevgi::Graphics::Element] root element
           # @param options [Hash] renderer options
           # @return [String] SVG fragment source
-          # @raise [Sevgi::ArgumentError] when style is missing or unsupported
+          # @raise [Sevgi::ArgumentError] when options, names, attributes, or content are invalid XML
           def self.fragment(root, **options) = new(root, **options).call
 
           # Appends rendered lines to the output buffer.
@@ -199,8 +200,9 @@ module Sevgi
           # Renders the document.
           # @param preambles [Array<String>] preamble lines
           # @return [String] SVG source
+          # @raise [Sevgi::ArgumentError] when a preamble or rendered value is not valid XML text
           def call(*preambles)
-            output.append(preambles) unless preambles.empty?
+            output.append(preambles.map { XML.text(it, context: "XML preamble") }) unless preambles.empty?
 
             root.Traverse(
               0,
@@ -234,6 +236,7 @@ module Sevgi
           end
 
           def build
+            validate_options!
             ArgumentError.("Missing style") unless options[:style]
 
             case options[:style]
@@ -254,10 +257,29 @@ module Sevgi
             element.children.empty? && element.contents.empty?
           end
 
+          def block_content?(element)
+            return false unless ELEMENTS_WITH_BLOCK_CONTENT.include?(element.name)
+
+            namespace = default_namespace(element)
+            namespace.nil? || namespace.to_s.empty? || namespace == SVG_NAMESPACE
+          end
+
           def closed = @closed = true
 
           def closed? = @closed.tap { unclosed }
 
+          def default_namespace(element)
+            current = element
+
+            while current.is_a?(Element)
+              return current.attributes[:xmlns] if current.attributes.has?(:xmlns)
+
+              current = current.parent
+            end
+
+            nil
+          end
+
           def contents(element, depth)
             return if element.contents.empty?
 
@@ -272,10 +294,10 @@ module Sevgi
           def floating?(element) = element.Is?(:_)
 
           def inline_content?(element)
-            return false if ELEMENTS_WITH_BLOCK_CONTENT.include?(element.name)
+            return false if block_content?(element)
             return false if floating?(element)
 
-            element.contents.size == 1 || ELEMENTS_WITH_INLINE_CONTENT.include?(element.name)
+            element.contents.any? || ELEMENTS_WITH_INLINE_CONTENT.include?(element.name)
           end
 
           def indent(depth)
@@ -284,7 +306,7 @@ module Sevgi
 
           def join
             inlines.join(output, indent: options[:indent], separator: SEPARATOR)
-            output.join(SEPARATOR)
+            XML.text(output.join(SEPARATOR), context: "SVG output")
           end
 
           def render_enter(element, depth)
@@ -307,6 +329,22 @@ module Sevgi
           end
 
           def unclosed = @closed = false
+
+          def validate_options!
+            unknown = options.keys - DEFAULTS.keys
+            ArgumentError.("Unknown renderer options: #{unknown.join(", ")}") unless unknown.empty?
+
+            indent = options[:indent]
+            unless indent.is_a?(::String) && /\A[\t\n\r ]*\z/.match?(indent)
+              ArgumentError.("Renderer indent must contain only XML whitespace")
+            end
+
+            options[:indent] = XML.text(indent, context: "Renderer indent")
+            linelength = options[:linelength]
+            return if linelength.is_a?(::Integer) && linelength >= 0
+
+            ArgumentError.("Renderer linelength must be a non-negative Integer")
+          end
         end
 
         private_constant :Renderer
@@ -315,10 +353,11 @@ module Sevgi
         #   Renders this element as SVG source.
         #   Elements with inline text content may also contain inline children such as `tspan`; the renderer keeps those
         #   descendants in the same text line. Whitespace inside content objects is preserved as given, and encoded
-        #   content is XML-escaped unless a verbatim content object is used.
+        #   content is XML-escaped unless a verbatim content object is used. SVG `style` elements use block content;
+        #   same-named elements under a foreign default namespace retain ordinary inline text formatting.
         #   @param options [Hash] renderer options
         #   @return [String] SVG source
-        #   @raise [Sevgi::ArgumentError] when style is missing or unsupported
+        #   @raise [Sevgi::ArgumentError] when options, preambles, names, attributes, or content are invalid XML
         def Render(**) = Renderer.(self, **)
 
         # Renders only this element's children.
@@ -326,7 +365,13 @@ module Sevgi
         # mixed-content formatting.
         # @param separator [String] separator between child documents
         # @return [String] rendered child fragments
-        def RenderChildren(separator = "\n\n") = children.map { Renderer.fragment(it) }.join(separator)
+        # @raise [Sevgi::ArgumentError] when separator or rendered child data is not valid XML text
+        def RenderChildren(separator = "\n\n")
+          ArgumentError.("SVG fragment separator must be a String") unless separator.is_a?(::String)
+
+          separator = XML.text(separator, context: "SVG fragment separator")
+          children.map { Renderer.fragment(it) }.join(separator)
+        end
       end
     end
   end

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

@@ -12,6 +12,9 @@ module Sevgi
 
         # Writes rendered SVG to standard output.
         # @param kwargs [Hash] render options
+        # @yield [content] optionally transforms rendered content before output
+        # @yieldparam content [String] rendered SVG source
+        # @yieldreturn [String] transformed SVG source
         # @return [Object] F.out return value
         def Out(**kwargs, &filter)
           F.out(self.(**kwargs), &filter)
@@ -21,6 +24,9 @@ module Sevgi
         # @param path [String, nil] output path or directory
         # @param default [String, nil] default output path
         # @param backup_suffix [String, nil] suffix used for an existing-file backup
+        # @yield [content] optionally transforms rendered content before output
+        # @yieldparam content [String] rendered SVG source
+        # @yieldreturn [String] transformed SVG source
         # @return [Object] F.out return value
         def Save(path = nil, default: nil, backup_suffix: nil, &filter)
           default ||= F.subext(EXT, caller_locations(1..1).first.path)
@@ -42,6 +48,9 @@ module Sevgi
         # Writes rendered SVG to a path.
         # @param path [String] output path
         # @param kwargs [Hash] render options
+        # @yield [content] optionally transforms rendered content before output
+        # @yieldparam content [String] rendered SVG source
+        # @yieldreturn [String] transformed SVG source
         # @return [Object] F.out return value
         def Write(path, **kwargs, &filter)
           F.out(self.(**kwargs), path, &filter)