sevgi-graphics 0.93.1 → 0.95.0

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
@@ -96,39 +97,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)
@@ -139,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(**)
@@ -154,9 +177,16 @@ 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 options, names, attributes, or content are invalid XML
+          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
@@ -170,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,
@@ -205,6 +236,7 @@ module Sevgi
           end
 
           def build
+            validate_options!
             ArgumentError.("Missing style") unless options[:style]
 
             case options[:style]
@@ -225,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?
 
@@ -243,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)
@@ -255,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)
@@ -278,21 +329,49 @@ 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
 
         # @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. 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.
+        # 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
+        # @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)

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

@@ -9,6 +9,9 @@ module Sevgi
         # @param mod [Module] callable drawing module
         # @param args [Array<Object>] callable arguments
         # @param kwargs [Hash] defs attributes
+        # @yield [name] converts each callable name to a symbol id
+        # @yieldparam name [Symbol] callable method name
+        # @yieldreturn [String, Symbol] symbol id
         # @return [Sevgi::Graphics::Element] defs element
         # @raise [Sevgi::ArgumentError] when mod is not a plain module
         def Symbols(mod, *args, **kwargs, &block)

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

@@ -18,6 +18,8 @@ module Sevgi
         # @param dy [Numeric] vertical spacing
         # @param oy [Numeric] vertical offset
         # @param proc [Proc, nil] optional coordinate/customization proc
+        # @yield evaluates the template drawing DSL in a generated group
+        # @yieldreturn [Object] ignored block result
         # @return [Sevgi::Graphics::Element] self
         # @raise [Sevgi::ArgumentError] when a required tile argument is missing or invalid
         def Tile(
@@ -67,6 +69,8 @@ module Sevgi
         # @param d [Numeric] horizontal spacing
         # @param o [Numeric] horizontal offset
         # @param proc [Proc, nil] optional coordinate/customization proc
+        # @yield evaluates the template drawing DSL in a generated group
+        # @yieldreturn [Object] ignored block result
         # @return [Sevgi::Graphics::Element] self
         # @raise [Sevgi::ArgumentError] when a required tile argument is missing or invalid
         def TileX(id = Undefined, n: Undefined, d: Undefined, o: 0, proc: nil, &block)
@@ -100,6 +104,8 @@ module Sevgi
         # @param d [Numeric] vertical spacing
         # @param o [Numeric] vertical offset
         # @param proc [Proc, nil] optional coordinate/customization proc
+        # @yield evaluates the template drawing DSL in a generated group
+        # @yieldreturn [Object] ignored block result
         # @return [Sevgi::Graphics::Element] self
         # @raise [Sevgi::ArgumentError] when a required tile argument is missing or invalid
         def TileY(id = Undefined, n: Undefined, d: Undefined, o: 0, proc: nil, &block)
@@ -135,9 +141,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 +153,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 cannot be stringified as valid XML or would form malformed markup
         def Comment(comment)
+          comment = XML.text(comment, context: "XML comment")
+
+          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/mixtures/validate.rb

@@ -4,6 +4,18 @@ module Sevgi
   module Graphics
     module Mixtures
       # DSL helpers for SVG standard validation.
+      #
+      # @!method CData
+      #   Returns text content used as SVG character data.
+      #   @return [String, nil] joined text content or nil
+      # @!method NS?(name)
+      #   Reports whether a namespace is available on this element or an ancestor.
+      #   @param name [Symbol, String] namespace suffix without xmlns:
+      #   @return [Boolean]
+      # @!method Validate
+      #   Validates this subtree against SVG standard metadata when that component is available.
+      #   @return [Sevgi::Graphics::Element, nil] self after validation, or nil without sevgi/standard
+      #   @raise [Sevgi::ValidationError] when SVG validation fails
       module Validate
         # Returns text content used as SVG character data.
         # @return [String, nil] joined text content or nil

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

@@ -27,6 +27,8 @@ module Sevgi
         # Builds a titled SVG symbol.
         # @param name [String] human-readable symbol name
         # @param kwargs [Hash] symbol attributes
+        # @yield evaluates the drawing DSL in the symbol element
+        # @yieldreturn [Object] ignored block result
         # @return [Sevgi::Graphics::Element] symbol element
         def Symbol(name, **kwargs, &block)
           id = (words = name.split).map(&:downcase).join("-")
@@ -63,7 +65,8 @@ module Sevgi
         # @param hash [Hash, nil] CSS rules
         # @param attributes [Hash] style attributes or CSS rules when hash is nil
         # @return [Sevgi::Graphics::Element] style element
-        # @raise [Sevgi::ArgumentError] when CSS content is not a hash
+        # @raise [Sevgi::ArgumentError] when CSS rules are malformed, cyclic, cannot be stringified, or contain invalid
+        #   encoding or illegal XML 1.0 characters
         def css(hash = nil, **attributes)
           hash, attributes = attributes, {} unless hash
 

data/lib/sevgi/graphics/mixtures.rb

@@ -8,11 +8,15 @@ module Sevgi
       #   Includes a named mixture and optional anonymous extension into a document class.
       #   @param mod [Symbol, String] mixture constant name
       #   @param document [Class] document class receiving the mixture
+      #   @yield defines methods in the anonymous mixture
+      #   @yieldreturn [Object] ignored module-definition result
       #   @return [Module, nil] optional anonymous mixture when a block is given
       #   @raise [NameError] when the mixture does not exist
       # @overload mixin(document = Graphics::Document::Base, &block)
       #   Includes only an anonymous extension into a document class.
       #   @param document [Class] document class receiving the mixture
+      #   @yield defines methods in the anonymous mixture
+      #   @yieldreturn [Object] ignored module-definition result
       #   @return [Module] anonymous mixture
       #   @raise [Sevgi::ArgumentError] when no named mixture or block is given
       def self.mixin(mod = Undefined, document = Graphics::Document::Base, &block)

data/lib/sevgi/graphics/version.rb

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

data/lib/sevgi/graphics/xml.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Sevgi
+  module Graphics
+    # XML 1.0 text and qualified-name validation shared by renderer boundaries.
+    # @api private
+    module XML
+      NCNAME_START = "A-Z_a-z\u{C0}-\u{D6}\u{D8}-\u{F6}\u{F8}-\u{2FF}\u{370}-\u{37D}\u{37F}-\u{1FFF}" \
+        "\u{200C}-\u{200D}\u{2070}-\u{218F}\u{2C00}-\u{2FEF}\u{3001}-\u{D7FF}\u{F900}-\u{FDCF}" \
+        "\u{FDF0}-\u{FFFD}\u{10000}-\u{EFFFF}"
+      NCNAME_CHAR = "#{NCNAME_START}\\-.0-9\u{B7}\u{300}-\u{36F}\u{203F}-\u{2040}".freeze
+      NCNAME = "[#{NCNAME_START}][#{NCNAME_CHAR}]*".freeze
+      QNAME = /\A#{NCNAME}(?::#{NCNAME})?\z/u
+
+      private_constant :NCNAME, :NCNAME_CHAR, :NCNAME_START, :QNAME
+
+      class << self
+        # Validates an XML 1.0 string representation.
+        # @param value [Object] value to stringify and validate
+        # @param context [String] error-message subject
+        # @return [String] UTF-8 text
+        # @raise [Sevgi::ArgumentError] when stringification, encoding, or XML character validation fails
+        def text(value, context: "XML content")
+          value = stringify(value, context:) unless value.is_a?(::String)
+          validate_string(value, context:)
+        end
+
+        # Validates and snapshots a nested XML-bound value.
+        # @param value [Object] scalar or nested container
+        # @param context [String] error-message subject
+        # @param seen [Hash] container identities on the current traversal path
+        # @return [Object] validated caller-owned snapshot
+        # @raise [Sevgi::ArgumentError] when the value is cyclic, collides after stringification, or has invalid XML text
+        def snapshot(value, context:, seen: {}.compare_by_identity)
+          case value
+          when ::Hash
+            nested(value, context:, seen:) { snapshot_hash(value, context:, seen:) }
+          when ::Array
+            nested(value, context:, seen:) { value.map { snapshot(it, context:, seen:) } }
+          else
+            text(value, context:)
+          end
+        end
+
+        # Validates an XML qualified name.
+        # @param value [Object] candidate name
+        # @param context [String] error-message subject
+        # @return [String] validated qualified name
+        # @raise [Sevgi::ArgumentError] when text conversion or QName validation fails
+        def name(value, context: "XML name")
+          text(value, context:).tap do |candidate|
+            ArgumentError.("#{context} is invalid: #{candidate.inspect}") unless QNAME.match?(candidate)
+          end
+        end
+
+        # Validates a nested XML value without retaining its snapshot.
+        # @param value [Object] scalar or nested container
+        # @param context [String] error-message subject
+        # @return [Object] original value
+        # @raise [Sevgi::ArgumentError] when nested content is cyclic or contains invalid XML text
+        def validate(value, context: "XML content")
+          snapshot(value, context:)
+          value
+        end
+
+        # Escapes embedded CDATA terminators after validating text.
+        # @param value [Object] CDATA value
+        # @return [String] safe CDATA body
+        # @raise [Sevgi::ArgumentError] when value is not valid XML text
+        def cdata(value) = text(value).gsub("]]>", "]]]]><![CDATA[>")
+
+        private
+
+        def nested(value, context:, seen:)
+          ArgumentError.("Cyclic #{context} is not supported") if seen.key?(value)
+
+          seen[value] = true
+          yield
+        ensure
+          seen.delete(value)
+        end
+
+        def snapshot_hash(value, context:, seen:)
+          value.each_with_object({}) do |(key, item), captured|
+            key = snapshot(key, context:, seen:)
+            ArgumentError.("#{context} keys collide after stringification") if captured.key?(key)
+
+            captured[key] = snapshot(item, context:, seen:)
+          end
+        end
+
+        def stringify(value, context:)
+          text = value.to_s
+          ArgumentError.("#{context} stringification must return a String") unless text.is_a?(::String)
+
+          text
+        rescue Sevgi::ArgumentError
+          raise
+        rescue ::StandardError => e
+          ArgumentError.("#{context} cannot be stringified: #{e.class}: #{e.message}")
+        end
+
+        def validate_string(value, context:)
+          ArgumentError.("#{context} must be valid UTF-8") unless value.valid_encoding?
+
+          text = value.encode("UTF-8")
+          if (codepoint = text.each_codepoint.find { !legal_codepoint?(it) })
+            ArgumentError.("#{context} contains illegal character U+#{format("%04X", codepoint)}")
+          end
+
+          text
+        rescue ::EncodingError => e
+          ArgumentError.("#{context} must be valid UTF-8: #{e.message}")
+        end
+
+        def legal_codepoint?(codepoint)
+          [0x9, 0xA, 0xD].include?(codepoint) ||
+            (0x20..0xD7FF).cover?(codepoint) ||
+            (0xE000..0xFFFD).cover?(codepoint) ||
+            (0x10000..0x10FFFF).cover?(codepoint)
+        end
+      end
+    end
+
+    private_constant :XML
+  end
+end

data/lib/sevgi/graphics.rb

@@ -2,6 +2,7 @@
 
 require "sevgi/function"
 
+require_relative "graphics/xml"
 require_relative "graphics/attribute"
 require_relative "graphics/auxiliary"
 require_relative "graphics/element"
@@ -24,27 +25,46 @@ 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)
+    #   Looks up a named profile when both definition keywords are omitted. Supplying `preambles:` or `attributes:`
+    #   defines a named profile, or returns an existing profile when every explicitly supplied field matches. Omitted
+    #   fields are ignored during existing-profile comparison. Profile containers and strings are copied into the
+    #   process-global, thread-atomic registry; mutable non-container attribute values are stringified once before
+    #   registration. Concurrent identical definitions return the same canonical registered class.
+    #   @param name [Symbol, String] profile name
+    #   @param preambles [Array<String>, nil, Sevgi::Undefined] document preamble lines
+    #   @param attributes [Hash, nil, Sevgi::Undefined] default root attributes; nil means an empty Hash
+    #   @return [Class] document class
+    #   @raise [Sevgi::ArgumentError] when a profile conflicts or metadata is invalid XML, cyclic, or cannot be stringified
+    # @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, nil, Sevgi::Undefined] default root attributes; nil means an empty Hash
+    #   @return [Class] anonymous document class
+    #   @raise [Sevgi::ArgumentError] when metadata is invalid XML, cyclic, or cannot be stringified
     # @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
 
     # Defines or replaces a document profile class.
+    # Validation and snapshot capture complete before an existing registration is atomically replaced.
     # @param name [Symbol, String] profile name
     # @param preambles [Array<String>, nil] document preamble lines
-    # @param attributes [Hash] default root attributes
+    # @param attributes [Hash, nil] default root attributes; nil means an empty Hash
     # @return [Class] document class
-    # @raise [Sevgi::ArgumentError] when the profile name is invalid
+    # @raise [Sevgi::ArgumentError] when the name or metadata is invalid XML, cyclic, or cannot be stringified
     def document!(name, preambles: [], attributes: {})
       Graphics::Document.define(name, preambles:, attributes:, overwrite: true)
     end
 
-    # Defines a paper profile unless the same profile already exists.
+    # Defines a paper profile unless the same profile already exists. Registration is process-global and thread-atomic;
+    # an identical concurrent definition is idempotent and a conflicting definition is rejected.
     # @param width [Numeric] paper width
     # @param height [Numeric] paper height
     # @param name [Symbol, String] profile name
@@ -52,13 +72,7 @@ module Sevgi
     # @return [Symbol, String] original profile name
     # @raise [Sevgi::ArgumentError] when the profile is invalid or an existing profile has different dimensions
     def paper(width, height, name = :custom, unit: "mm")
-      profile = Graphics::Paper[width, height, unit, name]
-
-      if Graphics::Paper.exist?(name)
-        ArgumentError.("Paper already defined differently: #{name}") unless Graphics::Paper.public_send(name) == profile
-      else
-        Graphics::Paper.define(name, width:, height:, unit:)
-      end
+      Graphics::Paper.define(name, width:, height:, unit:, overwrite: false)
 
       name
     end
@@ -77,9 +91,10 @@ module Sevgi
     # Builds an SVG root document.
     # @param document [Symbol, String, Class] document profile name or document class
     # @param canvas [Sevgi::Graphics::Canvas, Sevgi::Graphics::Paper, Symbol, String, Sevgi::Undefined, nil] canvas input
-    # @param block [Proc, nil] DSL block evaluated in the root element
+    # @yield evaluates the drawing DSL in the root element
+    # @yieldreturn [Object] ignored block result
     # @return [Sevgi::Graphics::Document::Proto] SVG root element
-    # @raise [Sevgi::ArgumentError] when the document or canvas profile is unknown
+    # @raise [Sevgi::ArgumentError] when the document/canvas profile or root XML attributes are invalid
     def SVG(document = :default, canvas = Undefined, **, &block)
       Graphics::Document.(document, canvas, **, &block)
     end