sevgi-graphics 0.93.1 → 0.94.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2aa7779435a4a7fb66f31fc412abac9eaf39f9f310d598a02a6fe0713e9aceab
-  data.tar.gz: 5f17372a0ff45b66c9388993c7270413b359d89889633bb775bac27747ff1128
+  metadata.gz: 74dd7631f2aeaa252c236f7dd1c372bd4860ebca07f23b787329aebdc04862b1
+  data.tar.gz: 04617a19db7b7e6485037ddd534f115f8c89d21dfd62cfa69de9fd8a6ff5a08f
 SHA512:
-  metadata.gz: 46fed1c304dc35516dc15e12eff33cfe5eea984ed070c675e62a8ecf659ad9f1aee3f5f1884525b98c622480c4d59ea72ab20b1d2d5b6704a30691026765bdfe
-  data.tar.gz: f35d041432cde1a165e8f753cbbe895dc2e90850a6f74cbcf89f4278ef60b022471072340959c9db21e96499ad45f09505416f7ef140b8ef620811319509a986
+  metadata.gz: 0acdf02ba08e49a7c3673e3457befc3c5270acb5fe05fd9985ec9d02b32f1231c79bc4127176ea3ebead9e3b9cd6e628af024e5de0aee951578eb72ff58e68d2
+  data.tar.gz: 90794ba32fd574c0747c61d71a7f0a47914bbf67a43e4239492cd97a8d9beec70cb482a9f2da5e095bf61e725f1dcafd2d4e0054561b884e0a6c32be5b8e2ee7

data/CHANGELOG.md

@@ -0,0 +1,4 @@
+# Changelog
+
+Sevgi Graphics follows the root Sevgi release notes:
+https://github.com/roktas/sevgi/blob/main/CHANGELOG.md

data/LICENSE

@@ -0,0 +1,5 @@
+Sevgi Graphics is distributed under the GNU General Public License v3.0 or later.
+
+SPDX-License-Identifier: GPL-3.0-or-later
+
+Full project license: https://github.com/roktas/sevgi/blob/main/LICENSE

data/README.md

@@ -1,5 +1,37 @@
 # Sevgi Graphics
 
-Provides the core SVG DSL, document profiles, and rendering behavior.
+Core SVG DSL, document profiles, and rendering behavior.
 
-See the root [README](../README.md) and the documentation site for usage.
+## Install
+
+```sh
+gem install sevgi-graphics
+```
+
+## Require
+
+```ruby
+require "sevgi/graphics"
+```
+
+## Example
+
+```ruby
+doc = Sevgi::Graphics.SVG(:minimal) { rect(width: 3, height: 5) }
+doc.call
+```
+
+## Ruby compatibility
+
+Requires Ruby 3.4.0 or newer. CI verifies Ruby 3.4 and the current development Ruby from `.ruby-version`.
+
+## Native prerequisites
+
+None beyond Ruby and this gem's Ruby dependencies.
+
+## Links
+
+- Documentation: https://sevgi.roktas.dev
+- API documentation: https://www.rubydoc.info/gems/sevgi-graphics
+- Source: https://github.com/roktas/sevgi/tree/main/graphics
+- Changelog: https://github.com/roktas/sevgi/blob/main/CHANGELOG.md

data/lib/sevgi/graphics/attribute.rb

@@ -41,6 +41,21 @@ module Sevgi
 
       extend Ident
 
+      # Returns the text form used for an XML attribute value before escaping.
+      # @param value [Object] attribute value
+      # @return [String]
+      # @api private
+      def self.xml_text(value)
+        case value
+        when ::Hash
+          value.map { |key, attr_value| "#{key}:#{attr_value}" }.join("; ")
+        when ::Array
+          value.join(" ")
+        else
+          value.to_s
+        end
+      end
+
       # Mutable SVG attribute store with Sevgi update syntax.
       class Store
         # Creates an attribute store.
@@ -60,7 +75,7 @@ module Sevgi
             .compact
             .to_a
             .to_h do |key, value|
-              [key.to_sym, value.is_a?(::Hash) ? value.transform_keys(&:to_sym) : value]
+              [key.to_sym, import_value(value)]
             end
 
           @store.merge!(hash)
@@ -143,6 +158,20 @@ module Sevgi
 
         private
 
+        # Returns a caller-owned value copy for import.
+        # @param value [Object] attribute value
+        # @return [Object] imported value
+        def import_value(value)
+          case value
+          when ::Hash
+            value.transform_keys(&:to_sym)
+          when ::Array
+            value.dup
+          else
+            value
+          end
+        end
+
         UPDATER = {
           ::String => proc { |old_value, new_value| [old_value, new_value].reject(&:empty?).join(" ") },
           ::Symbol => proc { |old_value, new_value| [old_value, new_value].reject(&:empty?).join(" ").to_sym },
@@ -164,16 +193,7 @@ module Sevgi
         private_constant :UPDATER
 
         def to_xml(id, value)
-          text = case value
-          when ::Hash
-            value.map { |key, attr_value| "#{key}:#{attr_value}" }.join("; ")
-          when ::Array
-            value.join(" ")
-          else
-            value.to_s
-          end
-
-          "#{id}=#{text.encode(xml: :attr)}"
+          "#{id}=#{Attribute.xml_text(value).encode(xml: :attr)}"
         end
       end
     end

data/lib/sevgi/graphics/auxiliary/canvas.rb

@@ -6,6 +6,10 @@ module Sevgi
   module Graphics
     # SVG canvas size, margins, viewport, and viewBox.
     class Canvas
+      ORIGIN_FIELDS = %i[x y].freeze
+      REPLACEMENTS = %i[width height unit name margins].freeze
+      private_constant :ORIGIN_FIELDS, :REPLACEMENTS
+
       # @overload call(arg = Undefined, **kwargs)
       #   Builds a canvas from a paper profile or explicit size.
       #   @param arg [Sevgi::Graphics::Paper, Symbol, String, Sevgi::Undefined] paper profile or paper object
@@ -91,8 +95,24 @@ module Sevgi
 
       # Returns a canvas with selected fields replaced.
       # @param kwargs [Hash] replacement options
+      # @option kwargs [Numeric] :width replacement canvas width
+      # @option kwargs [Numeric] :height replacement canvas height
+      # @option kwargs [Symbol, String] :unit replacement SVG unit
+      # @option kwargs [Symbol, String] :name replacement paper name
+      # @option kwargs [Array<Numeric>] :margins replacement margin shorthand values
       # @return [Sevgi::Graphics::Canvas]
-      def with(**kwargs) = self.class.new(**size.to_h, margins: kwargs.fetch(:margins, margin.to_a))
+      # @raise [Sevgi::ArgumentError] when an unknown option is supplied
+      # @raise [Sevgi::ArgumentError] when a replacement value is invalid
+      def with(**kwargs)
+        unknown = kwargs.keys - REPLACEMENTS
+
+        ArgumentError.("Unknown canvas option: #{unknown.first}") unless unknown.empty?
+
+        margins = kwargs.fetch(:margins, margin.to_a)
+        replacements = kwargs.dup.tap { it.delete(:margins) }
+
+        self.class.new(**size.to_h, **replacements, margins:)
+      end
 
       private
 
@@ -113,12 +133,20 @@ module Sevgi
         end
       end
 
+      def coordinate!(field, value)
+        Float(value)
+      rescue ::ArgumentError, ::TypeError
+        ArgumentError.("Invalid canvas origin #{field}: #{value.inspect}")
+      end
+
       def prettify(*floats)
         floats.map { (it % 1).zero? ? it.to_i : it }
       end
 
       def pair(array)
-        array.size == 2 ? array.map(&:to_f) : ArgumentError.("Argument must be an Array of size 2")
+        ArgumentError.("Canvas origin must have exactly two coordinates") unless array.size == 2
+
+        ORIGIN_FIELDS.zip(array).map { |field, value| coordinate!(field, value) }
       end
     end
   end

data/lib/sevgi/graphics/auxiliary/content.rb

@@ -27,11 +27,13 @@ module Sevgi
 
       # @overload cdata(content)
       #   Builds CDATA content.
+      #   Content values are stringified during rendering, and embedded CDATA terminators are split safely.
       #   @param content [Object] wrapped content
       #   @return [Sevgi::Graphics::Content::CData]
       def self.cdata(...) = CData.new(...)
 
       # Wraps content arguments, encoding non-content values.
+      # Non-content values are stringified by encoded content before XML text escaping.
       # @param args [Array<Object>] content arguments
       # @return [Array<Sevgi::Graphics::Content>]
       def self.contents(*args) = args.map { it.is_a?(Content) ? it : encoded(it) }
@@ -45,6 +47,7 @@ module Sevgi
 
       # @overload encoded(content)
       #   Builds XML text-encoded content.
+      #   Arbitrary objects are stringified before XML text escaping.
       #   @param content [Object] wrapped content
       #   @return [Sevgi::Graphics::Content::Encoded]
       def self.encoded(...) = Encoded.new(...)
@@ -62,7 +65,12 @@ module Sevgi
 
       # CDATA section content.
       class CData < Content
+        TERMINATOR = "]]>"
+        TERMINATOR_SPLIT = "]]]]><![CDATA[>"
+        private_constant :TERMINATOR, :TERMINATOR_SPLIT
+
         # Renders CDATA content.
+        # Embedded `]]>` terminators are split across adjacent CDATA sections so the output remains valid XML.
         # @param renderer [Object] renderer receiving output
         # @param depth [Integer] current render depth
         # @return [void]
@@ -70,9 +78,13 @@ module Sevgi
           depth += 1
 
           renderer.append(depth, "<![CDATA[")
-          renderer.append(depth + 1, *Array(content))
+          renderer.append(depth + 1, *Array(content).map { safe(it) })
           renderer.append(depth, "]]>")
         end
+
+        private
+
+        def safe(value) = value.to_s.gsub(TERMINATOR, TERMINATOR_SPLIT)
       end
 
       # CSS content rendered inside a CDATA section.
@@ -123,7 +135,7 @@ module Sevgi
       class Encoded < Content
         # Returns XML text-encoded content.
         # @return [String]
-        def to_s = content.encode(xml: :text)
+        def to_s = content.to_s.encode(xml: :text)
 
         # Renders encoded text content.
         # @param renderer [Object] renderer receiving output

data/lib/sevgi/graphics/document.rb

@@ -4,6 +4,50 @@ module Sevgi
   module Graphics
     # SVG document profile factory.
     module Document
+      # Defensive copy helper for profile metadata snapshots.
+      # @api private
+      module Snapshot
+        # Returns a recursively independent copy of a value.
+        # @param value [Object] value to copy
+        # @return [Object] copied value
+        def self.copy(value)
+          case value
+          when ::Hash
+            hash(value)
+          when ::Array
+            value.map { copy(it) }
+          else
+            duplicate(value)
+          end
+        end
+
+        # Returns a recursively frozen independent copy of a value.
+        # @param value [Object] value to copy and freeze
+        # @return [Object] frozen copied value
+        def self.frozen(value)
+          case value
+          when ::Hash
+            value.to_h { |key, item| [frozen(key), frozen(item)] }.freeze
+          when ::Array
+            value.map { frozen(it) }.freeze
+          else
+            duplicate(value).freeze
+          end
+        end
+
+        def self.hash(value) = value.to_h { |key, item| [copy(key), copy(item)] }
+
+        def self.duplicate(value)
+          value.dup
+        rescue ::TypeError
+          value
+        end
+
+        private_class_method :duplicate, :hash
+      end
+
+      private_constant :Snapshot
+
       # Builds a root SVG element from a document profile.
       # @param document [Symbol, String, Class] profile name or document class
       # @param canvas [Sevgi::Graphics::Canvas, Sevgi::Graphics::Paper, Symbol, String, Sevgi::Undefined, nil] canvas input
@@ -37,27 +81,47 @@ module Sevgi
 
       # Defines or returns a document profile class.
       # @param name [Symbol, String, Sevgi::Undefined] profile name, or Undefined for an anonymous profile
-      # @param preambles [Array<String>, nil] document preamble lines
-      # @param attributes [Hash] default root attributes
+      # @param preambles [Array<String>, nil, Sevgi::Undefined] document preamble lines
+      # @param attributes [Hash, Sevgi::Undefined] default root attributes
       # @param overwrite [Boolean] true to replace an existing profile
       # @return [Class] document class
       # @raise [Sevgi::ArgumentError] when a named profile conflicts with an existing profile
-      def self.define(name = Undefined, preambles: [], attributes: {}, overwrite: false)
-        return Class.new(Base) { document(name, preambles:, attributes:, register: false) } if name == Undefined
-
-        profile = Profile.new(name, attributes:, preambles:)
+      def self.define(name = Undefined, preambles: Undefined, attributes: Undefined, overwrite: false)
+        return anonymous(attributes:, preambles:) if name == Undefined
 
         if (current = Profile[name])
-          unless overwrite || current.profile == profile
-            ArgumentError.("Document profile already defined differently: #{name}")
-          end
-
+          reject_conflict(name, current, attributes:, preambles:) unless overwrite
           return current unless overwrite
         end
 
+        attributes, preambles = defaults(attributes:, preambles:)
         Class.new(Base) { document(name, preambles:, attributes:, overwrite:) }
       end
 
+      def self.anonymous(attributes:, preambles:)
+        attributes, preambles = defaults(attributes:, preambles:)
+        Class.new(Base) { document(Undefined, preambles:, attributes:, register: false) }
+      end
+
+      def self.defaults(attributes:, preambles:)
+        [attributes == Undefined ? {} : attributes, preambles == Undefined ? nil : preambles]
+      end
+
+      def self.reject_conflict(name, current, attributes:, preambles:)
+        return if compatible?(current, attributes:, preambles:)
+
+        ArgumentError.("Document profile already defined differently: #{name}")
+      end
+
+      def self.compatible?(klass, attributes:, preambles:)
+        profile = klass.profile
+
+        (attributes == Undefined || Profile.new(nil, attributes:).attributes == profile.attributes) &&
+          (preambles == Undefined || Profile.new(nil, preambles:).preambles == profile.preambles)
+      end
+
+      private_class_method :anonymous, :compatible?, :defaults, :reject_conflict
+
       # Immutable document profile metadata.
       # @api private
       class Profile
@@ -107,12 +171,6 @@ module Sevgi
         # @return [Symbol, nil] profile name
         attr_reader :name
 
-        # @return [Hash] default root attributes
-        attr_reader :attributes
-
-        # @return [Array<String>, nil] preamble lines
-        attr_reader :preambles
-
         # Creates profile metadata.
         # @param name [Object, nil] profile name
         # @param attributes [Hash, nil] default root attributes
@@ -121,8 +179,8 @@ module Sevgi
         # @raise [Sevgi::ArgumentError] when name cannot be normalized
         def initialize(name, attributes: nil, preambles: nil)
           @name = name.nil? ? nil : self.class.normalize!(name)
-          @attributes = attributes || {}
-          @preambles = preambles
+          @attributes = Snapshot.frozen(attributes || {})
+          @preambles = preambles.nil? ? nil : Snapshot.frozen(preambles)
         end
 
         # Reports strict profile equality.
@@ -130,9 +188,17 @@ module Sevgi
         # @return [Boolean]
         def ==(other) = self.class == other.class && deconstruct == other.deconstruct
 
+        # Returns default root attributes.
+        # @return [Hash] mutation-isolated attribute snapshot
+        def attributes = Snapshot.copy(@attributes)
+
         # Returns profile components.
         # @return [Array<(Symbol, nil), Hash, (Array<String>, nil)>]
         def deconstruct = [name, attributes, preambles]
+
+        # Returns preamble lines.
+        # @return [Array<String>, nil] mutation-isolated preamble snapshot
+        def preambles = Snapshot.copy(@preambles)
       end
 
       private_constant :Profile

data/lib/sevgi/graphics/element.rb

@@ -149,7 +149,7 @@ module Sevgi
 
       protected
 
-      attr_writer :children, :attributes
+      attr_writer :attributes, :children, :contents, :parent
     end
   end
 end

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

@@ -3,9 +3,20 @@
 module Sevgi
   module Graphics
     # Callable drawing module support.
-    # @api private
+    # Extend a plain Ruby module with this API to make its public instance methods callable drawing steps.
+    # @example Define and call a drawing module
+    #   Widget = Module.new do
+    #     extend Sevgi::Graphics::Module
+    #
+    #     def item(id)
+    #       rect(id:)
+    #     end
+    #   end
+    #
+    #   SVG { Call(Widget, "box") }
     module Module
-      # Tracks newly defined public methods as callable drawing steps.
+      # Tracks newly defined methods as callable drawing candidates.
+      # Invocation runs unique methods that are still public, preserving tracked definition order.
       # @param method [Symbol] method name Ruby reports as added
       # @return [Array<Symbol>, nil]
       def method_added(method)
@@ -49,6 +60,7 @@ module Sevgi
       #   @param args [Array<Object>] callable arguments
       #   @param kwargs [Hash] callable keyword arguments
       #   @return [Object, nil] last callable return value
+      #   @raise [Sevgi::ArgumentError] when mod is not a plain module
       def self.call(mod, receiver, ...)
         mod._befores.each { receiver.Within(receiver, &it) } if mod.respond_to?(:_befores) && mod._befores
         # return last callable return value
@@ -64,8 +76,22 @@ module Sevgi
       def self.callables(mod)
         ArgumentError.("Must be a module: #{mod}") unless mod.instance_of?(::Module)
 
-        (mod.respond_to?(:_callables) ? mod._callables : mod.instance_methods).map { mod.instance_method(it) }
+        callable_names(mod).uniq.filter_map do |name|
+          mod.instance_method(name) if mod.public_method_defined?(name)
+        end
       end
+
+      def self.callable_names(mod)
+        tracked = mod.ancestors.reverse_each.filter_map do |ancestor|
+          ancestor._callables if ancestor.respond_to?(:_callables)
+        end
+
+        return tracked.flatten unless tracked.empty?
+
+        mod.public_instance_methods
+      end
+
+      private_class_method :callable_names
     end
 
     module Mixtures

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

@@ -5,9 +5,15 @@ require "forwardable"
 module Sevgi
   module Graphics
     module Mixtures
-      # Internal traversal stop token.
+      # Traversal stop token returned by {Core#Stay}.
+      #
+      # @!attribute [r] value
+      #   @return [Object] value returned from traversal
+      Stop = Data.define(:value)
+
+      # Internal traversal engine.
       # @api private
-      Traversal = Data.define(:value) do
+      module Traversal
         # Runs a depth-first traversal.
         # @param element [Sevgi::Graphics::Element] starting element
         # @param depth [Integer] starting depth
@@ -21,7 +27,7 @@ module Sevgi
         end
 
         def self.stop(value)
-          throw(:traversal, value.value) if value.is_a?(self)
+          throw(:traversal, value.value) if value.is_a?(Stop)
         end
 
         def self.visit(element, depth, leave, &block)
@@ -46,6 +52,7 @@ module Sevgi
         # @param index [Integer] insertion index
         # @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
         def Adopt(new_parent = nil, index: -1)
           tap do
             if new_parent
@@ -56,6 +63,8 @@ module Sevgi
               new_parent = parent
             end
 
+            Adoption.validate(self, new_parent)
+
             self.Orphan()
             (@parent = new_parent).children.insert(index, self)
           end
@@ -65,6 +74,8 @@ module Sevgi
         #   Moves this element to the beginning of a parent.
         #   @param new_parent [Sevgi::Graphics::Element, nil] target parent or current parent
         #   @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
         def AdoptFirst(*)
           Adopt(*, index: 0)
         end
@@ -77,23 +88,22 @@ module Sevgi
         end
 
         # Adds CSS classes without duplicating existing values.
-        # @param classes [Array<String, Symbol>] class names
+        # @param classes [Array<String, Symbol, Array>] class tokens; strings are split on whitespace
         # @return [Sevgi::Graphics::Element] self
         def Classify(*classes)
           tap do
-            klasses = case self[:class]
-            when ::Array
-              self[:class]
-            when ::String
-              self[:class].split
-            when nil
-              []
-            else
-              [self[:class]]
+            tokens = proc do |value|
+              case value
+              when nil
+                []
+              when ::Array
+                value.flat_map { tokens.call(it) }
+              else
+                value.to_s.split
+              end
             end
 
-            classes.each { klasses << it unless klasses.include?(it) }
-            self[:class] = klasses
+            self[:class] = [*tokens.call(self[:class]), *tokens.call(classes)].uniq
           end
         end
 
@@ -112,7 +122,7 @@ 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
+        # @param contents [Array<Object>] text or content objects; non-content objects are stringified and XML-encoded
         # @param attributes [Hash] SVG attributes
         # @return [Sevgi::Graphics::Element] new child element
         def Element(tag, *contents, **attributes, &block)
@@ -168,8 +178,8 @@ module Sevgi
         # @overload Stay(value)
         #   Wraps a traversal return value as a stop token.
         #   @param value [Object] value returned from traversal
-        #   @return [Sevgi::Graphics::Mixtures::Traversal]
-        def Stay(...) = Traversal.new(...)
+        #   @return [Sevgi::Graphics::Mixtures::Stop]
+        def Stay(...) = Stop.new(...)
 
         # Traverses the subtree depth-first.
         # @param depth [Integer] starting depth
@@ -192,7 +202,7 @@ module Sevgi
           element = self
 
           loop do
-            yield(element, height).tap { return it.value if it.is_a?(Traversal) }
+            yield(element, height).tap { return it.value if it.is_a?(Stop) }
 
             break if element.Root?()
 
@@ -223,6 +233,28 @@ module Sevgi
         def <<(element)
           Append(element)
         end
+
+        # Adoption target validation that keeps tree mutation atomic.
+        # @api private
+        module Adoption
+          # 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
+          def self.validate(element, parent)
+            ArgumentError.("Element cannot be adopted under itself") if parent.equal?(element)
+
+            while parent.respond_to?(:Root?)
+              ArgumentError.("Element cannot be adopted under its descendant") if parent.equal?(element)
+              break if parent.Root?()
+
+              parent = parent.parent
+            end
+          end
+        end
+
+        private_constant :Adoption
       end
     end
   end

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

@@ -3,19 +3,24 @@
 module Sevgi
   module Graphics
     module Mixtures
-      # DSL helpers for duplicating elements and their subtrees.
+      # DSL helpers for duplicating independent element subtrees.
       module Duplicate
-        # Duplicates an element subtree and optionally translates it.
+        # 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
+        # @yield [element] optional customization hook for each copied element
+        # @yieldparam element [Sevgi::Graphics::Element] copied element
         # @return [Sevgi::Graphics::Element] duplicated element
+        # @raise [Sevgi::ArgumentError] when the target parent has a different element class
         def Duplicate(dx: nil, dy: nil, parent: nil, &block)
-          duplicated = dup
+          duplicated = Subtree.copy(self)
 
           duplicated.Traverse() do |element|
-            element.children = element.children.map(&:dup)
-            id = (element.attributes = element.attributes.dup).delete(:id)
+            id = element.attributes.delete(:id)
             element[:"#{ATTRIBUTE_INTERNAL_PREFIX}id"] = id if id
             block&.call(element)
           end
@@ -30,14 +35,39 @@ module Sevgi
         # Duplicates an element subtree along the x-axis.
         # @param dx [Numeric] x 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
         # @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)
 
         # 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
         # @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)
+
+        # 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.dup)
+              duplicated.send(:children=, element.children.map { |child| copy(child, duplicated) })
+            end
+          end
+        end
+
+        private_constant :Subtree
       end
     end
   end

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

@@ -10,7 +10,8 @@ module Sevgi
         # @param kwargs [Hash] export options
         # @return [String] output path
         # @raise [Sevgi::MissingComponentError] when sevgi/sundries is unavailable
-        # @raise [Sevgi::Sundries::ExportError] when native export fails
+        # @raise [Sevgi::MissingComponentError] when native export gems are unavailable
+        # @raise [Sevgi::Sundries::Export::ExportError] when native export fails
         def PDF(path = nil, **kwargs, &block)
           begin
             require "sevgi/sundries"
@@ -29,7 +30,8 @@ module Sevgi
         # @param kwargs [Hash] export options
         # @return [String] output path
         # @raise [Sevgi::MissingComponentError] when sevgi/sundries is unavailable
-        # @raise [Sevgi::Sundries::ExportError] when native export fails
+        # @raise [Sevgi::MissingComponentError] when native export gems are unavailable
+        # @raise [Sevgi::Sundries::Export::ExportError] when native export fails
         def PNG(path = nil, **kwargs, &block)
           begin
             require "sevgi/sundries"

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

@@ -45,7 +45,9 @@ module Sevgi
 
           def build
             element.Traverse() do |element|
-              next unless (id = element[:id])
+              next unless (value = element[:id])
+
+              id = Attribute.xml_text(value)
 
               if @namespace.key?(id)
                 (@collision[id] ||= [@namespace[id]]) << element

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

@@ -8,18 +8,27 @@ module Sevgi
         require "sevgi/derender"
 
         # Includes a derendered node matching an id.
+        #
+        # SVG/XML file 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] included element
+        # @return [Sevgi::Graphics::Element, nil] included element, or nil when the selected node produces no graphics
+        #   output
+        # @raise [Sevgi::ArgumentError] when the file cannot be found, file content is malformed or rootless, or the id is
+        #   absent
         # @raise [Sevgi::MissingComponentError] when sevgi/derender is unavailable
         def Include(file, id) = Derender.evaluate_file(file, self, id:)
 
         # Includes the children of a derendered node matching an id.
+        #
+        # SVG/XML file 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 cannot be found, file content is malformed or rootless, or the id is
+        #   absent
         # @raise [Sevgi::MissingComponentError] when sevgi/derender is unavailable
-        def IncludeChildren(file, id) = Derender.evaluate_file!(file, self, id:)
+        def IncludeChildren(file, id) = Derender.evaluate_file_children(file, self, id:)
       rescue ::LoadError => e
         raise unless e.path == "sevgi/derender"
 

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

@@ -96,39 +96,61 @@ module Sevgi
 
             # Creates an inline splice tracker.
             # @return [void]
-            def initialize = @marks = []
+            def initialize
+              @marks = []
+              @stack = []
+            end
 
             # Starts an inline splice range.
             # @param index [Integer] output index
             # @param depth [Integer] element depth
-            # @return [Array<Sevgi::Graphics::Mixtures::Render::Renderer::Inlines::Mark>]
-            def start(index, depth) = @marks << Mark.new(start: index, depth:)
+            # @return [Sevgi::Graphics::Mixtures::Render::Renderer::Inlines::Mark] opened mark
+            def start(index, depth)
+              Mark.new(start: index, depth:).tap do |mark|
+                @marks << mark
+                @stack << mark
+              end
+            end
 
-            # Ends the latest inline splice range.
+            # Ends the innermost inline splice range.
             # @param index [Integer] output index
             # @return [Integer]
-            def stop(index) = @marks.last.stop = index
+            # @raise [Sevgi::PanicError] when no inline range is open
+            def stop(index)
+              mark = @stack.pop
+              PanicError.("Inline content range was not opened") unless mark
+
+              mark.stop = index
+            end
 
             # Joins marked output ranges into inline content.
             # @param output [Array<Array<String>, nil>] renderer output buffer
             # @param indent [String] indentation unit
             # @param separator [String] line separator
             # @return [Array<Array<String>, nil>, nil]
+            # @raise [Sevgi::PanicError] when an inline range was not closed
             def join(output, indent:, separator:)
               return if @marks.empty?
 
-              @marks.each do |mark|
-                depth = mark.depth
-
-                ((mark.start + 1)..mark.stop).each do |i|
-                  output[i].map! { |line| line.delete_prefix(indent * (depth + 1)) }
-                  output[mark.start][-1] += output[i].join(separator)
-                  output[i] = nil
-                end
-              end
+              @marks.reverse_each { |mark| join_mark(output, mark, indent:, separator:) }
 
               output.compact!
             end
+
+            private
+
+            def join_mark(output, mark, indent:, separator:)
+              PanicError.("Inline content range was not closed") unless mark.stop
+
+              ((mark.start + 1)..mark.stop).each do |index|
+                lines = output[index]
+                next unless lines
+
+                lines.map! { |line| line.delete_prefix(indent * (mark.depth + 1)) }
+                output[mark.start][-1] += lines.join(separator)
+                output[index] = nil
+              end
+            end
           end
 
           # @overload initialize(root, **options)
@@ -157,6 +179,13 @@ module Sevgi
           #   @raise [Sevgi::ArgumentError] when style is missing or unsupported
           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
+          def self.fragment(root, **options) = new(root, **options).call
+
           # Appends rendered lines to the output buffer.
           # @param depth [Integer, nil] indentation depth
           # @param lines [Array<String>] rendered lines
@@ -284,15 +313,20 @@ module Sevgi
 
         # @overload Render(**options)
         #   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.
         #   @param options [Hash] renderer options
         #   @return [String] SVG source
         #   @raise [Sevgi::ArgumentError] when style is missing or unsupported
         def Render(**) = Renderer.(self, **)
 
         # Renders only this element's children.
+        # Child render output omits document preambles and preserves each child's text whitespace and inline
+        # mixed-content formatting.
         # @param separator [String] separator between child documents
-        # @return [String] rendered children
-        def RenderChildren(separator = "\n\n") = children.map(&:Render).join(separator)
+        # @return [String] rendered child fragments
+        def RenderChildren(separator = "\n\n") = children.map { Renderer.fragment(it) }.join(separator)
       end
     end
   end

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

@@ -135,9 +135,9 @@ module Sevgi
           # Argument validators for tile helpers.
           ASSERTION = {
             id: proc { |name, value| "Argument '#{name}' must be a string" unless value.is_a?(::String) },
-            n: proc { |name, value| "Argument '#{name}' must be a positive integer" unless value.positive? },
-            nx: proc { |name, value| "Argument '#{name}' must be a positive integer" unless value.positive? },
-            ny: proc { |name, value| "Argument '#{name}' must be a positive integer" unless value.positive? },
+            n: proc { |name, value| positive_integer_issue(name, value) },
+            nx: proc { |name, value| positive_integer_issue(name, value) },
+            ny: proc { |name, value| positive_integer_issue(name, value) },
             d: proc { |name, value| "Argument '#{name}' must be a number" unless value.is_a?(::Numeric) },
             dx: proc { |name, value| "Argument '#{name}' must be a number" unless value.is_a?(::Numeric) },
             dy: proc { |name, value| "Argument '#{name}' must be a number" unless value.is_a?(::Numeric) },
@@ -147,6 +147,14 @@ module Sevgi
             proc: proc { |name, value| "Argument '#{name}' must be a proc" unless value.nil? || value.is_a?(::Proc) }
           }.freeze
 
+          # Returns a validation issue unless value is a positive integer.
+          # @param name [Symbol] argument name
+          # @param value [Object] argument value
+          # @return [String, nil] validation issue
+          def positive_integer_issue(name, value)
+            "Argument '#{name}' must be a positive integer" unless value.is_a?(::Integer) && value.positive?
+          end
+
           # Validates tile arguments.
           # @param kwargs [Hash] tile arguments
           # @return [nil]

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

@@ -13,17 +13,28 @@ module Sevgi
         end
 
         # Adds an XML comment.
-        # @param comment [String] comment text
+        # @param comment [Object] comment text
         # @return [Sevgi::Graphics::Element] floating comment element
+        # @raise [Sevgi::ArgumentError] when comment text would produce malformed XML
         def Comment(comment)
+          comment = comment.to_s
+
+          ArgumentError.("XML comment must not contain '--'") if comment.include?("--")
+          ArgumentError.("XML comment must not end with '-'") if comment.end_with?("-")
+
           _(Content.verbatim("<!-- #{comment} -->"))
         end
 
-        # Merges internal ancestral attributes from the document root to this element.
+        # Merges internal attributes from the document root, ancestors, and this element.
+        # Only the direct root-to-self ancestor chain participates; sibling subtrees are ignored. When the same key is
+        # present on multiple chain elements, the nearest element to the receiver wins.
         # @return [Hash] merged internal attributes
         def Ancestral
+          chain = []
+          TraverseUp { |element| chain.unshift(element) }
+
           {}.tap do |result|
-            Root().Traverse() { |element| result.merge!(element[:_]) if element.has?(:_) }
+            chain.each { |element| result.merge!(element[:_]) if element.has?(:_) }
           end
         end
       end

data/lib/sevgi/graphics/version.rb

@@ -3,6 +3,6 @@
 module Sevgi
   module Graphics
     # Current graphics component version.
-    VERSION = "0.93.1"
+    VERSION = "0.94.0"
   end
 end

data/lib/sevgi/graphics.rb

@@ -24,13 +24,27 @@ module Sevgi
       Graphics::Canvas.from_paper(...)
     end
 
-    # Defines or returns a document profile class.
-    # @param name [Symbol, String, Sevgi::Undefined] profile name, or Undefined for an anonymous profile
-    # @param preambles [Array<String>, nil] document preamble lines
-    # @param attributes [Hash] default root attributes
+    # @overload document(name)
+    #   Looks up an existing document profile by name.
+    #   @param name [Symbol, String] profile name
+    #   @return [Class] document class
+    #   @raise [Sevgi::ArgumentError] when the profile is unknown
+    # @overload document(name, preambles: Undefined, attributes: Undefined)
+    #   Defines a named document profile, or returns an existing profile when every explicitly supplied field matches.
+    #   Omitted fields are ignored during existing-profile comparison. Profile inputs are copied into the registry.
+    #   @param name [Symbol, String] profile name
+    #   @param preambles [Array<String>, nil, Sevgi::Undefined] document preamble lines
+    #   @param attributes [Hash, Sevgi::Undefined] default root attributes
+    #   @return [Class] document class
+    #   @raise [Sevgi::ArgumentError] when a named profile conflicts with an existing profile
+    # @overload document(preambles: Undefined, attributes: Undefined)
+    #   Defines an anonymous document profile without registering it globally.
+    #   @param preambles [Array<String>, nil, Sevgi::Undefined] document preamble lines
+    #   @param attributes [Hash, Sevgi::Undefined] default root attributes
+    #   @return [Class] anonymous document class
+    #   @raise [Sevgi::ArgumentError] when profile input is invalid
     # @return [Class] document class
-    # @raise [Sevgi::ArgumentError] when a named profile conflicts with an existing profile
-    def document(name = Undefined, preambles: [], attributes: {})
+    def document(name = Undefined, preambles: Undefined, attributes: Undefined)
       Graphics::Document.define(name, preambles:, attributes:)
     end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sevgi-graphics
 version: !ruby/object:Gem::Version
-  version: 0.93.1
+  version: 0.94.0
 platform: ruby
 authors:
 - Recai Oktaş
@@ -15,20 +15,22 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.93.1
+        version: 0.94.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.93.1
+        version: 0.94.0
 description: Provides an extensible DSL for creating SVG content.
 email: roktas@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
+- LICENSE
 - README.md
 - lib/sevgi/graphics.rb
 - lib/sevgi/graphics/attribute.rb
@@ -80,7 +82,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.4.0.pre.preview1
+      version: 3.4.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="