sevgi-graphics 0.94.0 → 0.95.0

data/README.md

@@ -23,7 +23,7 @@ doc.call
 
 ## Ruby compatibility
 
-Requires Ruby 3.4.0 or newer. CI verifies Ruby 3.4 and the current development Ruby from `.ruby-version`.
+Requires Ruby 3.4.0 or newer. CI verifies Ruby 3.4.0 and the current development Ruby from `.ruby-version`.
 
 ## Native prerequisites
 

data/lib/sevgi/graphics/attribute.rb

@@ -20,33 +20,119 @@ module Sevgi
         # @param given [String, Symbol] attribute name
         # @return [Boolean]
         def internal?(given)
-          (@internal ||= {})[given] ||= given.start_with?(ATTRIBUTE_INTERNAL_PREFIX)
+          (@internal ||= {})[given] ||= key(given).start_with?(ATTRIBUTE_INTERNAL_PREFIX)
         end
 
         # Returns the normalized attribute id.
         # @param given [String, Symbol] attribute name
         # @return [Symbol]
         def id(given)
-          (@id ||= {})[given] ||= (updateable?(given) ? given.to_s.delete_suffix(ATTRIBUTE_UPDATE_SUFFIX) : given)
-            .to_sym
+          (@id ||= {})[given] ||= begin
+            name = updateable?(given) ? key(given).delete_suffix(ATTRIBUTE_UPDATE_SUFFIX) : key(given)
+            XML.name(name, context: "XML attribute name") unless internal?(given)
+            name.to_sym
+          end
         end
 
         # Reports whether an attribute uses merge/update syntax.
         # @param given [String, Symbol] attribute name
         # @return [Boolean]
         def updateable?(given)
-          (@updateable ||= {})[given] ||= given.end_with?(ATTRIBUTE_UPDATE_SUFFIX)
+          (@updateable ||= {})[given] ||= key(given).end_with?(ATTRIBUTE_UPDATE_SUFFIX)
+        end
+
+        private
+
+        def key(given)
+          return given.to_s if given.is_a?(::String) || given.is_a?(::Symbol)
+
+          ArgumentError.("XML attribute name must be a String or Symbol")
         end
       end
 
       extend Ident
 
+      # Owned mutable snapshots for values entering an attribute store.
+      # @api private
+      module Snapshot
+        class << self
+          def capture(value, normalize_keys: false, seen: {}.compare_by_identity)
+            case value
+            when ::Hash
+              nested(value, seen) { capture_hash(value, normalize_keys:, seen:) }
+            when ::Array
+              nested(value, seen) { value.map { capture(it, seen:) } }
+            else
+              capture_value(value)
+            end
+          end
+
+          private
+
+          def capture_hash(value, normalize_keys:, seen:)
+            identities = {}
+            value.each_with_object({}) do |(key, item), captured|
+              key = normalize_keys ? normalize_key(key) : capture(key, seen:)
+              identity = normalize_keys ? key : XML.snapshot(key, context: "XML attribute value")
+              if captured.key?(key) || identities.key?(identity)
+                ArgumentError.("Attribute keys collide after normalization or stringification")
+              end
+
+              identities[identity] = true
+              captured[key] = capture(item, seen:)
+            end
+          end
+
+          def capture_value(value)
+            text = XML.text(value, context: "XML attribute value")
+            case value
+            when ::Numeric, ::Symbol, ::NilClass, ::TrueClass, ::FalseClass
+              value
+            else
+              text
+            end
+          end
+
+          def nested(value, seen)
+            ArgumentError.("Cyclic XML attribute value is not supported") if seen.key?(value)
+
+            seen[value] = true
+            yield
+          ensure
+            seen.delete(value)
+          end
+
+          def normalize_key(key)
+            normalized = key.to_sym if key.respond_to?(:to_sym)
+            return normalized if normalized.is_a?(::Symbol)
+
+            ArgumentError.("Attribute Hash keys must normalize to Symbols")
+          rescue Sevgi::ArgumentError
+            raise
+          rescue ::StandardError => e
+            ArgumentError.("Attribute Hash key cannot be normalized: #{e.class}: #{e.message}")
+          end
+        end
+      end
+
+      private_constant :Snapshot
+
+      # Captures a caller-independent attribute value.
+      # @param value [Object] value to capture
+      # @param normalize_keys [Boolean] normalize direct Hash keys to Symbols
+      # @return [Object] owned mutable snapshot
+      # @raise [Sevgi::ArgumentError] when value is invalid, cyclic, collides, or cannot be converted
+      # @api private
+      def self.capture(value, normalize_keys: false) = Snapshot.capture(value, normalize_keys:)
+
       # Returns the text form used for an XML attribute value before escaping.
       # @param value [Object] attribute value
       # @return [String]
+      # @raise [Sevgi::ArgumentError] when value is invalid, cyclic, or cannot be stringified as XML
       # @api private
       def self.xml_text(value)
-        case value
+        value = XML.snapshot(value, context: "XML attribute value")
+        text = case value
         when ::Hash
           value.map { |key, attr_value| "#{key}:#{attr_value}" }.join("; ")
         when ::Array
@@ -54,61 +140,78 @@ module Sevgi
         else
           value.to_s
         end
+
+        XML.text(text, context: "XML attribute value")
       end
 
       # Mutable SVG attribute store with Sevgi update syntax.
       class Store
-        # Creates an attribute store.
+        # Creates an attribute store from recursively owned snapshots. Mutable non-container leaves are stringified
+        # once; later caller mutation cannot change the store.
         # @param attributes [Hash] initial attributes
         # @return [void]
+        # @raise [Sevgi::ArgumentError] when input is not a Hash or a name/value is invalid, cyclic, colliding, or cannot
+        #   be converted
         def initialize(attributes = {})
           @store = {}
 
           import(attributes)
         end
 
-        # Imports attributes into the store.
+        # Atomically imports recursively owned attribute snapshots.
         # @param attributes [Hash] attributes to merge
         # @return [Hash] internal store
+        # @raise [Sevgi::ArgumentError] when input is not a Hash or a name/value is invalid, cyclic, colliding, or cannot
+        #   be converted
         def import(attributes)
-          hash = attributes
-            .compact
-            .to_a
-            .to_h do |key, value|
-              [key.to_sym, import_value(value)]
-            end
+          ArgumentError.("Attributes must be imported from a Hash") unless attributes.is_a?(::Hash)
+
+          hash = attributes.each_with_object({}) do |(key, value), captured|
+            next if value.nil?
+
+            id = Attribute.id(key)
+            ArgumentError.("Attribute names collide after normalization: #{id}") if captured.key?(id)
+
+            captured[id] = Attribute.capture(value, normalize_keys: value.is_a?(::Hash))
+          end
 
           @store.merge!(hash)
         end
 
-        # Returns an attribute by normalized key.
+        # Returns a live stored attribute value. Mutating a returned container intentionally mutates this store; rendering
+        # revalidates the resulting value.
         # @param key [String, Symbol] attribute key
         # @return [Object, nil]
+        # @raise [Sevgi::ArgumentError] when key is not a valid XML attribute name
         def [](key)
           @store[Attribute.id(key)]
         end
 
-        # Assigns an attribute value.
+        # Assigns a recursively owned attribute snapshot. Mutable non-container leaves are stringified once.
         # @param key [String, Symbol] attribute key
         # @param value [Object, nil] attribute value; nil is ignored
-        # @return [Object, nil] assigned value or nil
+        # @return [Object, nil] stored snapshot or nil
         # @raise [Sevgi::ArgumentError] when update syntax receives incompatible values
         # @raise [Sevgi::ArgumentError] when update syntax receives an unsupported value type
+        # @raise [Sevgi::ArgumentError] when a name/value is invalid, cyclic, colliding, or cannot be converted
         def []=(key, value)
           return if value.nil?
 
-          @store[id = Attribute.id(key)] = @store.key?(id) && Attribute.updateable?(key) ? update(id, value) : value
+          id = Attribute.id(key)
+          value = Attribute.capture(value, normalize_keys: value.is_a?(::Hash))
+          @store[id] = @store.key?(id) && Attribute.updateable?(key) ? update(id, value) : value
         end
 
         # Deletes an attribute by normalized key.
         # @param key [String, Symbol] attribute key
         # @return [Object, nil] deleted value
+        # @raise [Sevgi::ArgumentError] when key is not a valid XML attribute name
         def delete(key)
           @store.delete(Attribute.id(key))
         end
 
-        # Returns public attributes ready for rendering.
-        # @return [Hash]
+        # Returns public attributes ready for rendering. Nested values remain live store values.
+        # @return [Hash] shallow attribute view
         def export
           hash = @store.reject { |id, _| Attribute.internal?(id) }
           return hash unless hash.key?(:id)
@@ -120,16 +223,18 @@ module Sevgi
         # Reports whether an attribute exists.
         # @param key [String, Symbol] attribute key
         # @return [Boolean]
+        # @raise [Sevgi::ArgumentError] when key is not a valid XML attribute name
         def has?(key)
           @store.key?(Attribute.id(key))
         end
 
-        # Copies the attribute store.
+        # Copies the attribute store with recursively independent values.
         # @param original [Sevgi::Graphics::Attribute::Store] store to copy
         # @return [void]
+        # @raise [Sevgi::ArgumentError] when live stored values became cyclic or invalid
         def initialize_copy(original)
           @store = {}
-          original.store.each { |key, value| @store[key] = value.dup }
+          original.store.each { |key, value| @store[key] = Attribute.capture(value) }
 
           super
         end
@@ -140,14 +245,16 @@ module Sevgi
           export.keys
         end
 
-        # Returns the internal attribute hash.
-        # @return [Hash]
+        # Returns the live internal attribute Hash. Mutating it intentionally mutates this store; rendering revalidates
+        # names and values.
+        # @return [Hash] live internal store
         def to_h
           @store
         end
 
         # Returns rendered XML attribute lines.
         # @return [Array<String>]
+        # @raise [Sevgi::ArgumentError] when stored names or values are invalid, cyclic, or cannot be stringified
         def to_xml_lines
           export.map { |id, value| to_xml(id, value) }
         end
@@ -158,20 +265,6 @@ 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 },
@@ -193,7 +286,8 @@ module Sevgi
         private_constant :UPDATER
 
         def to_xml(id, value)
-          "#{id}=#{Attribute.xml_text(value).encode(xml: :attr)}"
+          name = XML.name(id, context: "XML attribute name")
+          "#{name}=#{Attribute.xml_text(value).encode(xml: :attr)}"
         end
       end
     end

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

@@ -52,15 +52,19 @@ module Sevgi
       def_delegators :@margin, *Margin.members
       def_delegators :@size, *Paper.members
 
-      # @!attribute [r] size
-      #   @return [Sevgi::Graphics::Paper] paper size object
-      # @!attribute [r] margin
-      #   @return [Sevgi::Graphics::Margin] canvas margins
-      # @!attribute [r] inner
-      #   @return [Sevgi::Graphics::Paper] inner paper after margins
-      attr_reader :size, :margin, :inner
-
-      # Creates a canvas.
+      # Returns the paper size object.
+      # @return [Sevgi::Graphics::Paper]
+      attr_reader :size
+
+      # Returns the canvas margins.
+      # @return [Sevgi::Graphics::Margin]
+      attr_reader :margin
+
+      # Returns the inner paper after margins.
+      # @return [Sevgi::Graphics::Paper]
+      attr_reader :inner
+
+      # Creates a canvas with finite real dimensions greater than zero and margins that leave a positive inner area.
       # @param width [Numeric] canvas width
       # @param height [Numeric] canvas height
       # @param unit [Symbol, String] SVG unit
@@ -79,12 +83,12 @@ module Sevgi
       # @overload attributes(origin = Undefined)
       #   Returns SVG root viewport attributes.
       #   @param origin [Numeric, Array<Numeric>, nil, Sevgi::Undefined] viewBox origin
-      #   @return [Hash]
+      #   @return [Hash{Symbol => String}] SVG viewport and viewBox attributes
       #   @raise [Sevgi::ArgumentError] when origin is invalid
       def attributes(...) = {**viewport, viewBox: viewbox(...)}
 
       # Returns SVG width and height attributes.
-      # @return [Hash]
+      # @return [Hash{Symbol => String}] SVG width and height attributes
       def viewport = {width: "#{width}#{unit}", height: "#{height}#{unit}"}
 
       # Returns the SVG viewBox string.
@@ -117,7 +121,21 @@ module Sevgi
       private
 
       def compute
-        @inner = size.with(width: width - margin.left - margin.right, height: height - margin.top - margin.bottom)
+        @inner = size.with(**inner_size)
+        ensure_inner_area
+      end
+
+      def ensure_inner_area
+        return if @inner.width.positive? && @inner.height.positive?
+
+        ArgumentError.("Canvas margins must leave a positive inner area")
+      end
+
+      def inner_size
+        {
+          width: width - margin.left - margin.right,
+          height: height - margin.top - margin.bottom
+        }
       end
 
       def originate(origin)
@@ -125,7 +143,7 @@ module Sevgi
         when Undefined
           [-margin.left, -margin.top]
         when ::Numeric, ::NilClass
-          [origin.to_f, origin.to_f]
+          scalar_origin(origin)
         when ::Array
           pair(origin)
         else
@@ -134,9 +152,13 @@ module Sevgi
       end
 
       def coordinate!(field, value)
-        Float(value)
-      rescue ::ArgumentError, ::TypeError
-        ArgumentError.("Invalid canvas origin #{field}: #{value.inspect}")
+        return 0.0 if value.nil?
+
+        Scalar.finite(value, context: "canvas origin", field:)
+      end
+
+      def scalar_origin(origin)
+        coordinate!(:origin, origin || 0).then { [it, it] }
       end
 
       def prettify(*floats)

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

@@ -2,16 +2,101 @@
 
 module Sevgi
   module Graphics
-    # Renderable text-like content inside an SVG element.
+    # Renderable text-like content inside an SVG element. Content owns an immutable deep snapshot: strings and containers
+    # are copied, mutable leaf objects are stringified once during construction, and {#content} returns caller-owned
+    # copies. Later mutations cannot change rendering or invalidate the construction-time XML checks.
     class Content
-      # @!attribute [r] content
-      #   @return [Object] wrapped content
-      attr_reader :content
+      # Immutable payload capture and caller-owned copy helpers.
+      # @api private
+      module Snapshot
+        SCALARS = [::NilClass, ::TrueClass, ::FalseClass, ::Symbol, ::Integer, ::Float, ::Rational, ::Complex].freeze
+        private_constant :SCALARS
 
-      # Creates content.
+        class << self
+          def capture(value, seen = {}.compare_by_identity)
+            case value
+            when ::String
+              XML.text(value).freeze
+            when ::Hash
+              nested(value, seen) { capture_hash(value, seen) }.freeze
+            when ::Array
+              nested(value, seen) { value.map { capture(it, seen) } }.freeze
+            else
+              SCALARS.include?(value.class) ? value : stringify(value).freeze
+            end
+          end
+
+          def copy(value)
+            case value
+            when ::String
+              value.dup
+            when ::Hash
+              value.to_h { |key, item| [copy(key), copy(item)] }
+            when ::Array
+              value.map { copy(it) }
+            else
+              value
+            end
+          end
+
+          private
+
+          def capture_hash(value, seen)
+            value.each_with_object({}) do |(key, item), captured|
+              key = capture(key, seen)
+              ArgumentError.("XML content keys collide after stringification") if captured.key?(key)
+
+              captured[key] = capture(item, seen)
+            end
+          end
+
+          def nested(value, seen)
+            ArgumentError.("Cyclic XML content is not supported") if seen.key?(value)
+
+            seen[value] = true
+            yield
+          ensure
+            seen.delete(value)
+          end
+
+          def stringify(value)
+            text = value.to_s
+            ArgumentError.("XML content stringification must return a String") unless text.is_a?(::String)
+
+            XML.text(text)
+          rescue Sevgi::ArgumentError
+            raise
+          rescue ::StandardError => e
+            ArgumentError.("XML content cannot be stringified: #{e.class}: #{e.message}")
+          end
+        end
+      end
+
+      private_constant :Snapshot
+
+      # Returns a recursively independent, caller-owned payload snapshot.
+      # @return [Object] wrapped content snapshot
+      def content = Snapshot.copy(@content)
+
+      # Creates immutable content from a deep payload snapshot. Strings and containers are copied recursively; mutable
+      # non-container objects are stringified once during construction. The caller's objects are never retained.
       # @param content [Object] wrapped content
       # @return [void]
-      def initialize(content) = @content = content
+      # @raise [Sevgi::ArgumentError] when content cannot be stringified, contains invalid encoding or illegal XML
+      #   characters, contains cycles, or has keys that collide after stringification
+      def initialize(content)
+        @content = Snapshot.capture(content)
+        XML.validate(@content)
+      end
+
+      # Copies content payload ownership for duplicated element trees.
+      # @param original [Sevgi::Graphics::Content] source content
+      # @return [void]
+      # @api private
+      def initialize_copy(original)
+        @content = Snapshot.capture(original.content)
+        super
+      end
 
       # Renders content with a renderer.
       # @abstract Subclasses implement content rendering.
@@ -23,33 +108,45 @@ module Sevgi
 
       # Returns content as a string.
       # @return [String]
-      def to_s = content.to_s
+      def to_s = XML.text(payload)
+
+      def payload = @content
+
+      private :payload
 
       # @overload cdata(content)
       #   Builds CDATA content.
-      #   Content values are stringified during rendering, and embedded CDATA terminators are split safely.
+      #   Mutable objects are stringified during construction, and embedded CDATA terminators are split safely.
       #   @param content [Object] wrapped content
       #   @return [Sevgi::Graphics::Content::CData]
+      #   @raise [Sevgi::ArgumentError] when content cannot be stringified, contains invalid encoding or illegal XML 1.0
+      #     characters, contains cycles, or has keys that collide after stringification
       def self.cdata(...) = CData.new(...)
 
       # Wraps content arguments, encoding non-content values.
-      # Non-content values are stringified by encoded content before XML text escaping.
+      # Mutable non-content values are stringified by encoded content during construction, before XML text escaping.
       # @param args [Array<Object>] content arguments
       # @return [Array<Sevgi::Graphics::Content>]
+      # @raise [Sevgi::ArgumentError] when an argument cannot be stringified, contains invalid encoding or illegal XML
+      #   1.0 characters, contains cycles, or has keys that collide after stringification
       def self.contents(*args) = args.map { it.is_a?(Content) ? it : encoded(it) }
 
       # @overload css(content)
       #   Builds CSS content.
       #   @param content [Hash] CSS rules
       #   @return [Sevgi::Graphics::Content::CSS]
-      #   @raise [Sevgi::ArgumentError] when content is not a hash
+      #   @raise [Sevgi::ArgumentError] when content is not a hash, contains a malformed style, cannot be stringified,
+      #     contains invalid encoding or illegal XML 1.0 characters, contains cycles, or has keys that collide after
+      #     stringification
       def self.css(...) = CSS.new(...)
 
       # @overload encoded(content)
       #   Builds XML text-encoded content.
-      #   Arbitrary objects are stringified before XML text escaping.
+      #   Mutable objects are stringified during construction before XML text escaping.
       #   @param content [Object] wrapped content
       #   @return [Sevgi::Graphics::Content::Encoded]
+      #   @raise [Sevgi::ArgumentError] when content cannot be stringified, contains invalid encoding or illegal XML 1.0
+      #     characters, contains cycles, or has keys that collide after stringification
       def self.encoded(...) = Encoded.new(...)
 
       # Joins content lines with newlines.
@@ -59,16 +156,17 @@ module Sevgi
 
       # @overload verbatim(content)
       #   Builds verbatim content.
+      #   Mutable objects are stringified during construction.
       #   @param content [Object] wrapped content
       #   @return [Sevgi::Graphics::Content::Verbatim]
+      #   @raise [Sevgi::ArgumentError] when content cannot be stringified, contains invalid encoding or illegal XML 1.0
+      #     characters, contains cycles, or has keys that collide after stringification
       def self.verbatim(...) = Verbatim.new(...)
 
-      # CDATA section content.
+      # CDATA section content backed by an immutable payload snapshot. Mutable leaf objects are stringified during
+      # construction; embedded terminators are split during rendering.
+      # @see Content.cdata
       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
@@ -78,23 +176,28 @@ module Sevgi
           depth += 1
 
           renderer.append(depth, "<![CDATA[")
-          renderer.append(depth + 1, *Array(content).map { safe(it) })
+          renderer.append(depth + 1, *Array(payload).map { safe(it) })
           renderer.append(depth, "]]>")
         end
 
         private
 
-        def safe(value) = value.to_s.gsub(TERMINATOR, TERMINATOR_SPLIT)
+        def safe(value) = XML.cdata(value)
       end
 
-      # CSS content rendered inside a CDATA section.
+      # CSS content rendered inside a CDATA section. Rules are captured recursively during construction; mutable
+      # selectors, property names, and values are stringified once, and embedded CDATA terminators are split safely.
+      # @see Content.css
       class CSS < Content
         # Creates CSS content.
         # @param content [Hash] CSS rules
         # @return [void]
-        # @raise [Sevgi::ArgumentError] when content is not a hash
+        # @raise [Sevgi::ArgumentError] when content is not a hash, contains a malformed style, cannot be stringified,
+        #   contains invalid encoding or illegal XML 1.0 characters, contains cycles, or has keys that collide after
+        #   stringification
         def initialize(content)
-          ArgumentError.("CSS content must be a hash: #{content}") unless content.is_a?(::Hash)
+          ArgumentError.("CSS content must be a hash") unless content.is_a?(::Hash)
+          validate_styles(content)
 
           super
         end
@@ -104,21 +207,20 @@ module Sevgi
         # @param renderer [Object] renderer receiving output
         # @param depth [Integer] current render depth
         # @return [void]
-        # @raise [Sevgi::ArgumentError] when a style value cannot be rendered
         def render(renderer, depth)
           depth += 1
 
           renderer.append(depth, "<![CDATA[")
 
           depth += 1
-          content.each do |rule, styles|
+          payload.each do |rule, styles|
             case styles
             when ::Hash
-              renderer.append(depth, "#{rule} {")
-              renderer.append(depth + 1, *styles.map { |key, value| "#{key}: #{value};" })
+              renderer.append(depth, safe("#{rule} {"))
+              renderer.append(depth + 1, *styles.map { |key, value| safe("#{key}: #{value};") })
               renderer.append(depth, "}")
             when ::String, ::Symbol, ::Numeric
-              renderer.append(depth, "#{rule}: #{styles};")
+              renderer.append(depth, safe("#{rule}: #{styles};"))
             else
               ArgumentError.("Malformed style: #{styles}")
             end
@@ -129,13 +231,27 @@ module Sevgi
           renderer.append(depth, "]]>")
         end
         # rubocop:enable Metrics/MethodLength
+
+        private
+
+        def safe(value) = XML.cdata(value)
+
+        def validate_styles(content)
+          content.each_value do |styles|
+            next if styles.is_a?(::Hash) || styles.is_a?(::String) || styles.is_a?(::Symbol) || styles.is_a?(::Numeric)
+
+            ArgumentError.("Malformed style type: #{styles.class}")
+          end
+        end
       end
 
-      # XML text-encoded content.
+      # XML text-encoded content backed by an immutable payload snapshot. Mutable leaf objects are stringified during
+      # construction, before XML escaping.
+      # @see Content.encoded
       class Encoded < Content
         # Returns XML text-encoded content.
         # @return [String]
-        def to_s = content.to_s.encode(xml: :text)
+        def to_s = XML.text(payload).encode(xml: :text)
 
         # Renders encoded text content.
         # @param renderer [Object] renderer receiving output
@@ -144,8 +260,15 @@ module Sevgi
         def render(renderer, depth) = renderer.append(depth + 1, to_s)
       end
 
-      # Verbatim content rendered without XML text encoding.
+      # Verbatim content backed by an immutable payload snapshot. Mutable leaf objects are stringified during
+      # construction. Verbatim content bypasses XML escaping; validation guarantees encoding and legal XML 1.0 code
+      # points, not well-formed markup supplied by the caller.
+      # @see Content.verbatim
       class Verbatim < Content
+        # Returns validated verbatim content.
+        # @return [String]
+        def to_s = XML.text(payload)
+
         # Renders verbatim content.
         # @param renderer [Object] renderer receiving output
         # @param depth [Integer] current render depth