sevgi-graphics 0.94.0 → 0.98.2

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

@@ -4,73 +4,108 @@ require "forwardable"
 
 module Sevgi
   module Graphics
-    # SVG canvas size, margins, viewport, and viewBox.
+    # Immutable SVG canvas size, margins, viewport, and viewBox.
+    #
+    # `size` is the outer paper. `inner` subtracts the margins but remains a
+    # size value, not a positioned rectangle. By default the viewBox origin is
+    # the negative left/top margin, so drawing coordinates `(0, 0)` begin at the
+    # inner area's top-left while the SVG viewport still includes the margins.
+    # Pass nil to {#viewbox} or {#attributes} for a literal zero origin.
+    # @example Build from a paper profile or an explicit size
+    #   page = Sevgi::Graphics::Canvas.from_paper(:a4, margins: [10])
+    #   icon = Sevgi::Graphics::Canvas.call(width: 24, height: 24, unit: :px)
+    #   page.viewbox       # uses the negative left and top margins as its origin
+    #   icon.viewbox(nil)  # uses `0 0` as its origin
+    # @see Sevgi::Graphics::Document
+    # @see Sevgi::Sundries::Grid
     class Canvas
+      DEFAULTS = {unit: "mm", name: :custom, margins: []}.freeze
+      FIELDS = %i[width height unit name margins].freeze
       ORIGIN_FIELDS = %i[x y].freeze
-      REPLACEMENTS = %i[width height unit name margins].freeze
-      private_constant :ORIGIN_FIELDS, :REPLACEMENTS
+      REQUIRED = %i[width height].freeze
+      private_constant :DEFAULTS, :FIELDS, :ORIGIN_FIELDS, :REQUIRED
 
-      # @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
-      #   @param kwargs [Hash] canvas keyword arguments
+      # @overload call(paper, **overrides)
+      #   Builds a canvas from a paper profile with optional field overrides.
+      #   @param paper [Sevgi::Graphics::Paper, Symbol, String] paper object or registered profile
+      #   @param overrides [Hash] canvas field overrides
       #   @return [Sevgi::Graphics::Canvas]
-      #   @raise [Sevgi::ArgumentError] when the paper profile is unknown
-      def self.call(...) = from_paper(...)
+      #   @raise [Sevgi::ArgumentError] when the paper or an override is invalid
+      # @overload call(width:, height:, unit: "mm", name: :custom, margins: [])
+      #   Builds a canvas from an explicit size.
+      #   @param width [Numeric] canvas width
+      #   @param height [Numeric] canvas height
+      #   @param unit [Symbol, String] SVG unit
+      #   @param name [Symbol, String] paper name
+      #   @param margins [Array<Numeric>] margin shorthand values
+      #   @return [Sevgi::Graphics::Canvas]
+      #   @raise [Sevgi::ArgumentError] when a required field is omitted or a value is invalid
+      def self.call(paper = Undefined, **fields)
+        paper.equal?(Undefined) ? new(**fields) : from_paper(paper, **fields)
+      end
 
-      # Builds a canvas from a paper profile or explicit size.
-      # @param arg [Sevgi::Graphics::Paper, Symbol, String, Sevgi::Undefined] paper profile or paper object
-      # @param kwargs [Hash] canvas keyword arguments
-      # @return [Sevgi::Graphics::Canvas]
-      # @raise [Sevgi::ArgumentError] when the paper profile is unknown
-      def self.from_paper(arg = Undefined, **kwargs)
-        case arg
-        when Undefined
-          new(**kwargs)
-        else
-          new(**paper(arg).to_h, **kwargs)
-        end
+      # @overload from_paper(paper, **overrides)
+      #   Builds a canvas from a paper profile with optional field overrides.
+      #   @param paper [Sevgi::Graphics::Paper, Symbol, String] paper object or registered profile
+      #   @param overrides [Hash] canvas field overrides
+      #   @return [Sevgi::Graphics::Canvas]
+      #   @raise [Sevgi::ArgumentError] when the paper is omitted or invalid, or an override is invalid
+      # @example Override a registered paper profile
+      #   Sevgi::Graphics::Canvas.from_paper(:a4, margins: [10])
+      def self.from_paper(paper = Undefined, **overrides)
+        ArgumentError.("Paper is required") if paper.equal?(Undefined)
+
+        new(**profile(paper).to_h, **overrides)
       end
 
-      def self.paper(arg)
-        case arg
+      def self.profile(paper)
+        case paper
         when Paper
-          arg
+          paper
         when ::Symbol, ::String
-          ArgumentError.("Unknown paper profile: #{arg}") unless Paper.exist?(arg)
-
-          Paper.public_send(arg)
+          Paper.fetch(paper)
         else
-          ArgumentError.("Argument must be a Paper symbol: #{arg}")
+          ArgumentError.("Paper must be a Paper, Symbol, or String: #{paper}")
         end
       end
 
-      private_class_method :paper
+      private_class_method :profile
 
       extend Forwardable
 
       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.
-      # @param width [Numeric] canvas width
-      # @param height [Numeric] canvas height
-      # @param unit [Symbol, String] SVG unit
-      # @param name [Symbol, String] paper name
-      # @param margins [Array<Numeric>] margin shorthand values
-      # @return [void]
-      # @raise [Sevgi::ArgumentError] when margins or numeric dimensions are invalid
-      def initialize(width:, height:, unit: "mm", name: :custom, margins: [])
-        @size = Paper[width, height, unit, name]
-        @margin = Margin[*margins]
+      # 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
+
+      # @overload initialize(width:, height:, unit: "mm", name: :custom, margins: [])
+      #   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
+      #   @param name [Symbol, String] paper name
+      #   @param margins [Array<Numeric>] margin shorthand values
+      #   @return [void]
+      #   @raise [Sevgi::ArgumentError] when a required field is omitted, an option is unknown, or a value is invalid
+      def initialize(**fields)
+        unknown = fields.keys - FIELDS
+        ArgumentError.("Unknown canvas option: #{unknown.first}") unless unknown.empty?
+        ArgumentError.("Canvas width and height are required") unless REQUIRED.all? { fields.key?(it) }
+
+        fields = DEFAULTS.merge(fields)
+
+        @size = Paper[*fields.values_at(:width, :height, :unit, :name)]
+        @margin = Margin[*fields[:margins]]
 
         compute
         freeze
@@ -78,22 +113,48 @@ module Sevgi
 
       # @overload attributes(origin = Undefined)
       #   Returns SVG root viewport attributes.
-      #   @param origin [Numeric, Array<Numeric>, nil, Sevgi::Undefined] viewBox origin
-      #   @return [Hash]
+      #   Omission uses the negative left and top margins; nil uses zero for both coordinates.
+      #   @example Compare margin-aware and zero-origin viewBoxes
+      #     canvas = Sevgi::Graphics::Canvas.call(width: 80, height: 50, margins: [5, 10])
+      #     canvas.attributes[:viewBox] # => "-10 -5 80 50"
+      #     canvas.attributes(nil)[:viewBox] # => "0 0 80 50"
+      #   @param origin [Numeric, Array<Numeric>, nil, Sevgi::Undefined] viewBox origin; a scalar sets both coordinates
+      #   @return [Hash{Symbol => String}] SVG viewport and viewBox attributes
       #   @raise [Sevgi::ArgumentError] when origin is invalid
       def attributes(...) = {**viewport, viewBox: viewbox(...)}
 
+      # Reports structural canvas equality by size and margins.
+      # @example Compare equivalent canvas values
+      #   Sevgi::Graphics::Canvas.from_paper(:a4, margins: [10]) ==
+      #     Sevgi::Graphics::Canvas.from_paper("a4", margins: [10]) # => true
+      # @param other [Object] object to compare
+      # @return [Boolean]
+      def eql?(other) = self.class == other.class && size.eql?(other.size) && margin.eql?(other.margin)
+
+      # Returns a hash compatible with structural equality.
+      # @return [Integer]
+      def hash = [self.class, size, margin].hash
+
+      alias == eql?
+
       # 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.
-      # @param origin [Numeric, Array<Numeric>, nil, Sevgi::Undefined] viewBox origin
+      # Omission uses the negative left and top margins; nil uses zero for both coordinates.
+      # @param origin [Numeric, Array<Numeric>, nil, Sevgi::Undefined] viewBox origin; a scalar sets both coordinates
       # @return [String]
       # @raise [Sevgi::ArgumentError] when origin is invalid
       def viewbox(origin = Undefined) = prettify(*originate(origin), width, height).join(" ")
 
       # Returns a canvas with selected fields replaced.
+      # Unspecified fields, including margins, retain their current values.
+      # @example Derive a canvas while preserving the source
+      #   source = Sevgi::Graphics::Canvas.call(width: 80, height: 50, margins: [5])
+      #   derived = source.with(width: 100, margins: [10, 5])
+      #   source.width # => 80.0
+      #   derived.inner.deconstruct # => [90.0, 30.0, :mm, :custom]
       # @param kwargs [Hash] replacement options
       # @option kwargs [Numeric] :width replacement canvas width
       # @option kwargs [Numeric] :height replacement canvas height
@@ -104,7 +165,7 @@ module Sevgi
       # @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
+        unknown = kwargs.keys - FIELDS
 
         ArgumentError.("Unknown canvas option: #{unknown.first}") unless unknown.empty?
 
@@ -117,7 +178,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 +200,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 +209,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,123 +2,246 @@
 
 module Sevgi
   module Graphics
-    # Renderable text-like content inside an SVG element.
+    # Extensible protocol for renderable text-like content inside an SVG element. Use {.cdata}, {.css}, {.encoded}, or
+    # {.verbatim} for built-in content, or subclass Content and implement {#render} for a custom serialization. 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.
+    #
+    # @abstract Subclasses implement {#render} and expose their own construction API.
+    # @example Choose a built-in content channel
+    #   Sevgi::Graphics.SVG(:minimal) do
+    #     text "A & B" # ordinary String arguments are encoded automatically
+    #     text Sevgi::Graphics::Content.encoded("A & B")
+    #     style Sevgi::Graphics::Content.cdata(".note { fill: red; }")
+    #     style Sevgi::Graphics::Content.css(".note" => {fill: "red"})
+    #     g Sevgi::Graphics::Content.verbatim("<title>trusted markup</title>")
+    #   end
+    # @example Define custom content that emits an SVG tspan
+    #   class Emphasis < Sevgi::Graphics::Content
+    #     def self.[](content) = send(:new, content)
+    #
+    #     def render(output, depth)
+    #       text = Sevgi::Graphics::Content.encoded(to_s).to_s
+    #       output.append(depth + 1, %(<tspan font-style="italic">#{text}</tspan>))
+    #     end
+    #   end
+    #
+    #   Sevgi::Graphics.SVG(:minimal) { text Emphasis["important & safe"] }.Render
+    #
+    #   # The renderer ignores Emphasis#render's return value. Custom content must escape inserted data itself.
+    # @see https://sevgi.roktas.dev/svg/#content-safety Content safety guide
     class Content
-      # @!attribute [r] content
-      #   @return [Object] wrapped content
-      attr_reader :content
+      private_class_method :new
 
-      # Creates 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
+
+        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
+      # @api private
+      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.
+      private :initialize_copy
+
+      # Appends this content's serialized XML lines to rendering output.
+      # The output collaborator responds to `append(depth, *lines)`, where `depth` is an Integer or nil and every line
+      # is a String containing valid serialized XML text. The rendering engine ignores both `append` and `render` return
+      # values. Custom content is responsible for escaping data that it inserts into markup.
       # @abstract Subclasses implement content rendering.
-      # @param _renderer [Object] renderer receiving output
+      # @param _output [#append] rendering output collaborator
       # @param _depth [Integer] current render depth
-      # @return [void]
+      # @return [Object] ignored by the rendering engine
       # @raise [Sevgi::PanicError] when a subclass does not implement render
-      def render(_renderer, _depth) = PanicError.("#{self.class}#render must be implemented")
+      def render(_output, _depth) = PanicError.("#{self.class}#render must be implemented")
 
       # 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]
-      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) }
+      #   @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.send(:new, ...)
 
       # @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
-      def self.css(...) = CSS.new(...)
+      #   @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.send(: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]
-      def self.encoded(...) = Encoded.new(...)
-
-      # Joins content lines with newlines.
-      # @param contents [Object, Array<Object>] content lines
-      # @return [String]
-      def self.text(contents) = Array(contents).join("\n")
+      #   @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.send(:new, ...)
 
       # @overload verbatim(content)
       #   Builds verbatim content.
+      #   Mutable objects are stringified during construction.
       #   @param content [Object] wrapped content
       #   @return [Sevgi::Graphics::Content::Verbatim]
-      def self.verbatim(...) = Verbatim.new(...)
+      #   @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.send(: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
+        # @param renderer [#append] rendering output collaborator
         # @param depth [Integer] current render depth
-        # @return [void]
+        # @return [Object] ignored by the rendering engine
         def render(renderer, depth)
           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
+        # @api private
         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
 
-        # rubocop:disable Metrics/MethodLength
         # Renders CSS content.
-        # @param renderer [Object] renderer receiving output
+        # @param renderer [#append] rendering output collaborator
         # @param depth [Integer] current render depth
-        # @return [void]
-        # @raise [Sevgi::ArgumentError] when a style value cannot be rendered
+        # @return [Object] ignored by the rendering engine
         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
@@ -128,28 +251,48 @@ 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
+        # @param renderer [#append] rendering output collaborator
         # @param depth [Integer] current render depth
-        # @return [void]
+        # @return [Object] ignored by the rendering engine
         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 renderer [#append] rendering output collaborator
         # @param depth [Integer] current render depth
-        # @return [void]
+        # @return [Object] ignored by the rendering engine
         def render(renderer, depth) = renderer.append(depth + 1, to_s)
       end
     end