sevgi-graphics 0.95.0 → 0.98.2

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

@@ -4,6 +4,12 @@ module Sevgi
   module Graphics
     module Mixtures
       # DSL helpers for SVG transform attributes.
+      #
+      # Transform calls are appended in call order and return the element, so they can be composed.
+      # @example Compose transforms on one element
+      #   Sevgi::Graphics.SVG(:minimal) do
+      #     rect(width: 8, height: 4).Translate(12, 6).Rotate(15, 4, 2)
+      #   end
       module Transform
         # Aligns an inner box inside an outer box.
         # @param position [Symbol, String, nil] alignment name
@@ -11,12 +17,15 @@ module Sevgi
         # @param outer [#width, #height, nil] outer box
         # @return [Sevgi::Graphics::Element] self
         # @raise [Sevgi::ArgumentError] when alignment is unsupported
+        # @raise [Sevgi::ArgumentError] when a box dimension is not a finite real number
         def Align(position, inner:, outer:)
           return self unless position && inner && outer
 
           case position.to_sym
           when :center
-            Translate((outer.width - inner.width) / 2.0, (outer.height - inner.height) / 2.0)
+            dimensions = [inner.width, inner.height, outer.width, outer.height]
+            iw, ih, ow, oh = dimensions.map { Scalar.number(it, context: "alignment", field: :dimension) }
+            Translate((ow - iw) / 2.0, (oh - ih) / 2.0)
           else
             ArgumentError.("Unsupported alignment: #{position}")
           end
@@ -26,7 +35,7 @@ module Sevgi
         # @return [Sevgi::Graphics::Element] self
         def Flip
           tap do
-            attributes[:"transform#{ATTRIBUTE_UPDATE_SUFFIX}"] = "scale(-1, -1)"
+            attributes[:"transform#{Attributes::UPDATE_SUFFIX}"] = "scale(-1, -1)"
           end
         end
 
@@ -34,7 +43,7 @@ module Sevgi
         # @return [Sevgi::Graphics::Element] self
         def FlipX
           tap do
-            attributes[:"transform#{ATTRIBUTE_UPDATE_SUFFIX}"] = "scale(-1, 1)"
+            attributes[:"transform#{Attributes::UPDATE_SUFFIX}"] = "scale(-1, 1)"
           end
         end
 
@@ -42,36 +51,40 @@ module Sevgi
         # @return [Sevgi::Graphics::Element] self
         def FlipY
           tap do
-            attributes[:"transform#{ATTRIBUTE_UPDATE_SUFFIX}"] = "scale(1, -1)"
+            attributes[:"transform#{Attributes::UPDATE_SUFFIX}"] = "scale(1, -1)"
           end
         end
 
         # Appends a six-value SVG matrix transform.
-        # @param values [Array<Numeric>] matrix values
+        # @param values [Array<Numeric>] finite matrix values, normalized to SVG numbers
         # @return [Sevgi::Graphics::Element] self
-        # @raise [Sevgi::ArgumentError] when exactly six values are not supplied
+        # @raise [Sevgi::ArgumentError] when six finite real values are not supplied
         def Matrix(*values)
           tap do
             ArgumentError.("Incorrect transform matrix (six values required): #{values}") if values.size != 6
+            values = Scalar.numbers(values, context: "matrix")
 
-            attributes[:"transform#{ATTRIBUTE_UPDATE_SUFFIX}"] = "matrix(#{values.join(" ")})"
+            attributes[:"transform#{Attributes::UPDATE_SUFFIX}"] = "matrix(#{values.join(" ")})"
           end
         end
 
         # Appends an SVG rotate transform.
-        # @param a [Numeric] angle in degrees
-        # @param origin [Array<Numeric>] optional x and y origin
+        # @param a [Numeric] finite angle in degrees, normalized to an SVG number
+        # @param origin [Array<Numeric>] optional finite x and y origin, normalized to SVG numbers
         # @return [Sevgi::Graphics::Element] self
-        # @raise [Sevgi::ArgumentError] when origin is not two coordinates
+        # @raise [Sevgi::ArgumentError] when angle or origin is not finite real, or origin is not two coordinates
         def Rotate(a, *origin)
           tap do
             if !origin.empty? && origin.size != 2
               ArgumentError.("Incorrect origin (two coordinates required): #{origin}")
             end
 
-            next if a.to_f == 0.0
+            angle = Scalar.number(a, context: "rotation", field: :angle)
+            origin = Scalar.numbers(origin, context: "rotation")
 
-            attributes[:"transform#{ATTRIBUTE_UPDATE_SUFFIX}"] = "rotate(#{[a, *origin].join(", ")})"
+            next if angle.zero?
+
+            attributes[:"transform#{Attributes::UPDATE_SUFFIX}"] = "rotate(#{[angle, *origin].join(", ")})"
           end
         end
 
@@ -88,56 +101,83 @@ module Sevgi
         def RotateLeft(...) = Rotate(-90, ...)
 
         # Appends an SVG scale transform.
-        # @param x [Numeric] x scale, or uniform scale when y is nil
-        # @param y [Numeric, nil] y scale
+        # @param x [Numeric] finite x scale, or uniform scale when y is nil
+        # @param y [Numeric, nil] finite y scale
         # @return [Sevgi::Graphics::Element] self
+        # @raise [Sevgi::ArgumentError] when a scale is not a finite real number
         def Scale(x, y = nil)
           tap do
-            attributes[:"transform#{ATTRIBUTE_UPDATE_SUFFIX}"] = "scale(#{(y ? [x, y] : [x]).join(", ")})"
+            x = Scalar.number(x, context: "scale", field: :x)
+            y = Scalar.number(y, context: "scale", field: :y) unless y.nil?
+            attributes[:"transform#{Attributes::UPDATE_SUFFIX}"] = "scale(#{(y.nil? ? [x] : [x, y]).join(", ")})"
           end
         end
 
         # Appends a skew transform through an SVG matrix.
-        # @param ax [Numeric] x skew angle in degrees
-        # @param ay [Numeric] y skew angle in degrees
+        # @param ax [Numeric] finite x skew angle in degrees, normalized before calculation
+        # @param ay [Numeric] finite y skew angle in degrees, normalized before calculation
         # @return [Sevgi::Graphics::Element] self
+        # @raise [Sevgi::ArgumentError] when an angle is not a finite real number
         def Skew(ax, ay)
+          ax = Scalar.number(ax, context: "skew", field: :x)
+          ay = Scalar.number(ay, context: "skew", field: :y)
           Matrix(1.0, ::Math.tan(ay / 180.0 * ::Math::PI), ::Math.tan(ax / 180.0 * ::Math::PI), 1.0, 0.0, 0.0)
         end
 
         # Appends an SVG skewX transform.
-        # @param a [Numeric] angle in degrees
+        # @param a [Numeric] finite angle in degrees, normalized to an SVG number
         # @return [Sevgi::Graphics::Element] self
+        # @raise [Sevgi::ArgumentError] when angle is not a finite real number
         def SkewX(a)
           tap do
-            next if a.to_f == 0.0
+            angle = Scalar.number(a, context: "skew", field: :x)
+            next if angle.zero?
 
-            attributes[:"transform#{ATTRIBUTE_UPDATE_SUFFIX}"] = "skewX(#{a})"
+            attributes[:"transform#{Attributes::UPDATE_SUFFIX}"] = "skewX(#{angle})"
           end
         end
 
         # Appends an SVG skewY transform.
-        # @param a [Numeric] angle in degrees
+        # @param a [Numeric] finite angle in degrees, normalized to an SVG number
         # @return [Sevgi::Graphics::Element] self
+        # @raise [Sevgi::ArgumentError] when angle is not a finite real number
         def SkewY(a)
           tap do
-            next if a.to_f == 0.0
+            angle = Scalar.number(a, context: "skew", field: :y)
+            next if angle.zero?
 
-            attributes[:"transform#{ATTRIBUTE_UPDATE_SUFFIX}"] = "skewY(#{a})"
+            attributes[:"transform#{Attributes::UPDATE_SUFFIX}"] = "skewY(#{angle})"
           end
         end
 
-        # Appends an SVG translate transform.
-        # @param x [Numeric] x translation
-        # @param y [Numeric, nil] y translation
+        # Appends an SVG translate transform. One argument translates only the x axis.
+        # @param x [Numeric] finite x translation, normalized to an SVG number
+        # @param y [Numeric, nil] finite y translation, normalized to an SVG number
         # @return [Sevgi::Graphics::Element] self
+        # @raise [Sevgi::ArgumentError] when a coordinate is not a finite real number
         def Translate(x, y = nil)
           tap do
-            next if x.to_f == 0.0 && (y.nil? || y.to_f == 0.0)
+            dx = Scalar.number(x, context: "translation", field: :x)
+            dy = Scalar.number(y, context: "translation", field: :y) unless y.nil?
+            next if dx.zero? && (dy.nil? || dy.zero?)
 
-            attributes[:"transform#{ATTRIBUTE_UPDATE_SUFFIX}"] = "translate(#{(y ? [x, y] : [x]).join(" ")})"
+            attributes[:"transform#{Attributes::UPDATE_SUFFIX}"] = "translate(#{(dy.nil? ? [dx] : [dx, dy]).join(" ")})"
           end
         end
+
+        # Appends an x-axis SVG translate transform.
+        # @param x [Numeric] finite x translation
+        # @return [Sevgi::Graphics::Element] self
+        # @raise [Sevgi::ArgumentError] when x is not a finite real number
+        # @see #Translate
+        def TranslateX(x) = Translate(x)
+
+        # Appends a y-axis SVG translate transform.
+        # @param y [Numeric] finite y translation
+        # @return [Sevgi::Graphics::Element] self
+        # @raise [Sevgi::ArgumentError] when y is not a finite real number
+        # @see #Translate
+        def TranslateY(y) = Translate(0, y)
       end
     end
   end

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

@@ -3,8 +3,11 @@
 module Sevgi
   module Graphics
     module Mixtures
-      # DSL helpers for floating text, comments, and inherited internal attributes.
+      # DSL helpers for floating text, comments, and inherited non-rendering context.
       module Underscore
+        CONTEXT = :"#{Attributes::META_PREFIX}context"
+        private_constant :CONTEXT
+
         # Creates a floating content element.
         # @param contents [Array<Object>] text or content objects
         # @return [Sevgi::Graphics::Element] floating element
@@ -25,16 +28,22 @@ module Sevgi
           _(Content.verbatim("<!-- #{comment} -->"))
         end
 
-        # Merges internal attributes from the document root, ancestors, and this element.
+        # Merges `-context` metadata 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
+        # present on multiple chain elements, the nearest element to the receiver wins. Context remains available in
+        # memory but is omitted from rendered SVG. It is unrelated to the `_:` XML namespace syntax preserved by
+        # Derender.
+        # @return [Hash] merged context
+        # @example Inherit drawing context without rendering it
+        #   Sevgi::Graphics.SVG "-context": {tone: "tomato"} do
+        #     rect fill: Ancestral()[:tone]
+        #   end
         def Ancestral
           chain = []
           TraverseUp { |element| chain.unshift(element) }
 
           {}.tap do |result|
-            chain.each { |element| result.merge!(element[:_]) if element.has?(:_) }
+            chain.each { |element| result.merge!(element[CONTEXT]) if element.has?(CONTEXT) }
           end
         end
       end

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

@@ -22,7 +22,7 @@ module Sevgi
         def CData
           return if !contents || contents.empty?
 
-          Content.text(contents)
+          contents.join("\n")
         end
 
         # Reports whether a namespace is available on this element or an ancestor.
@@ -41,7 +41,7 @@ module Sevgi
           Traverse do |element|
             Standard.conform(
               element.name,
-              attributes: element.attributes.list,
+              attributes: element.attributes.keys,
               cdata: element.CData(),
               elements: element.children.map(&:name)
             )

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

@@ -6,21 +6,34 @@ module Sevgi
       # DSL wrappers for common SVG shapes and content patterns.
       module Wrappers
         # Builds a line path ending at an absolute point.
-        # @param x2 [Numeric] ending x coordinate
-        # @param y2 [Numeric] ending y coordinate
-        # @param x1 [Numeric] starting x coordinate
-        # @param y1 [Numeric] starting y coordinate
+        # @example Render a rational coordinate as an SVG number
+        #   Sevgi::Graphics.SVG { LineTo(x2: Rational(1, 2), y2: 1) }
+        # @param x2 [Numeric] finite ending x coordinate
+        # @param y2 [Numeric] finite ending y coordinate
+        # @param x1 [Numeric] finite starting x coordinate
+        # @param y1 [Numeric] finite starting y coordinate
         # @return [Sevgi::Graphics::Element] path element
+        # @raise [Sevgi::ArgumentError] when a coordinate is not a finite real number
         def LineTo(x2:, y2:, x1: 0, y1: 0, **)
+          x1 = Scalar.number(x1, context: "absolute line", field: :x1)
+          y1 = Scalar.number(y1, context: "absolute line", field: :y1)
+          x2 = Scalar.number(x2, context: "absolute line", field: :x2)
+          y2 = Scalar.number(y2, context: "absolute line", field: :y2)
+
           path(d: "M #{x1} #{y1} L #{x2} #{y2}", **)
         end
 
         # Builds a horizontal line path ending at an absolute x coordinate.
-        # @param x2 [Numeric] ending x coordinate
-        # @param x1 [Numeric] starting x coordinate
-        # @param y1 [Numeric] starting y coordinate
+        # @param x2 [Numeric] finite ending x coordinate
+        # @param x1 [Numeric] finite starting x coordinate
+        # @param y1 [Numeric] finite starting y coordinate
         # @return [Sevgi::Graphics::Element] path element
+        # @raise [Sevgi::ArgumentError] when a coordinate is not a finite real number
         def HLineTo(x2:, x1: 0, y1: 0, **)
+          x1 = Scalar.number(x1, context: "horizontal line", field: :x1)
+          y1 = Scalar.number(y1, context: "horizontal line", field: :y1)
+          x2 = Scalar.number(x2, context: "horizontal line", field: :x2)
+
           path(d: "M #{x1} #{y1} H #{x2}", **)
         end
 
@@ -41,23 +54,36 @@ module Sevgi
         end
 
         # Builds a vertical line path ending at an absolute y coordinate.
-        # @param y2 [Numeric] ending y coordinate
-        # @param x1 [Numeric] starting x coordinate
-        # @param y1 [Numeric] starting y coordinate
+        # @param y2 [Numeric] finite ending y coordinate
+        # @param x1 [Numeric] finite starting x coordinate
+        # @param y1 [Numeric] finite starting y coordinate
         # @return [Sevgi::Graphics::Element] path element
+        # @raise [Sevgi::ArgumentError] when a coordinate is not a finite real number
         def VLineTo(y2:, x1: 0, y1: 0, **)
+          x1 = Scalar.number(x1, context: "vertical line", field: :x1)
+          y1 = Scalar.number(y1, context: "vertical line", field: :y1)
+          y2 = Scalar.number(y2, context: "vertical line", field: :y2)
+
           path(d: "M #{x1} #{y1} V #{y2}", **)
         end
 
         # Builds a relative line path from angle and length.
-        # @param angle [Numeric] angle in degrees
-        # @param length [Numeric] line length
-        # @param x [Numeric] starting x coordinate
-        # @param y [Numeric] starting y coordinate
+        # @param angle [Numeric] finite angle in degrees, normalized before calculation
+        # @param length [Numeric] finite line length, normalized before calculation
+        # @param x [Numeric] finite starting x coordinate, normalized to an SVG number
+        # @param y [Numeric] finite starting y coordinate, normalized to an SVG number
         # @return [Sevgi::Graphics::Element] path element
+        # @raise [Sevgi::ArgumentError] when an operand is not a finite real number
         def LineBy(angle:, length:, x: 0, y: 0, **)
-          dx = length * ::Math.cos(angle.to_f / 180 * ::Math::PI)
-          dy = length * ::Math.sin(angle.to_f / 180 * ::Math::PI)
+          angle, length, x, y = Scalar.numbers([angle, length, x, y], context: "relative line")
+          dx, dy = Scalar.numbers(
+            [
+              length * ::Math.cos(angle.to_f / 180 * ::Math::PI),
+              length * ::Math.sin(angle.to_f / 180 * ::Math::PI)
+            ],
+            context: "relative line result"
+          )
+
           path(d: "M #{x} #{y} l #{dx} #{dy}", **)
         end
 
@@ -74,27 +100,40 @@ module Sevgi
         end
 
         # Builds a relative horizontal line path.
-        # @param length [Numeric] line length
-        # @param x [Numeric] starting x coordinate
-        # @param y [Numeric] starting y coordinate
+        # @param length [Numeric] finite line length
+        # @param x [Numeric] finite starting x coordinate
+        # @param y [Numeric] finite starting y coordinate
         # @return [Sevgi::Graphics::Element] path element
+        # @raise [Sevgi::ArgumentError] when an operand is not a finite real number
         def HLineBy(length:, x: 0, y: 0, **)
+          length = Scalar.number(length, context: "horizontal line", field: :length)
+          x = Scalar.number(x, context: "horizontal line", field: :x)
+          y = Scalar.number(y, context: "horizontal line", field: :y)
+
           path(d: "M #{x} #{y} h #{length}", **)
         end
 
         # Builds a square rect.
-        # @param length [Numeric] side length
+        # @param length [Numeric] finite side length
         # @return [Sevgi::Graphics::Element] rect element
+        # @raise [Sevgi::ArgumentError] when length is not a finite real number
         def square(length:, **)
+          length = Scalar.number(length, context: "square", field: :length)
+
           rect(width: length, height: length, **)
         end
 
         # Builds a relative vertical line path.
-        # @param length [Numeric] line length
-        # @param x [Numeric] starting x coordinate
-        # @param y [Numeric] starting y coordinate
+        # @param length [Numeric] finite line length
+        # @param x [Numeric] finite starting x coordinate
+        # @param y [Numeric] finite starting y coordinate
         # @return [Sevgi::Graphics::Element] path element
+        # @raise [Sevgi::ArgumentError] when an operand is not a finite real number
         def VLineBy(length:, x: 0, y: 0, **)
+          length = Scalar.number(length, context: "vertical line", field: :length)
+          x = Scalar.number(x, context: "vertical line", field: :x)
+          y = Scalar.number(y, context: "vertical line", field: :y)
+
           path(d: "M #{x} #{y} v #{length}", **)
         end
       end

data/lib/sevgi/graphics/mixtures.rb

@@ -23,26 +23,28 @@ module Sevgi
         mod, document = normalize(mod, document, block)
         ArgumentError.("Mixture name or block required") if mod == Undefined && !block
 
-        document.mixture(mod) unless mod == Undefined
+        document.send(:mixture, mod) unless mod == Undefined
         include_anonymous(document, &block) if block
       end
 
-      def self.anonymous_document?(mod, block)
-        block && mod.is_a?(::Class) && mod <= Graphics::Document::Proto
-      end
+      class << self
+        private
 
-      def self.include_anonymous(document, &block)
-        ::Module.new(&block).tap do |anonymous|
-          document.send(:include, anonymous)
-          document.extend(anonymous.const_get(:ClassMethods)) if anonymous.const_defined?(:ClassMethods, false)
+        def anonymous_document?(mod, block)
+          block && mod.is_a?(::Class) && mod <= Graphics::Document::Proto
         end
-      end
 
-      def self.normalize(mod, document, block)
-        anonymous_document?(mod, block) ? [Undefined, mod] : [mod, document]
-      end
+        def include_anonymous(document, &block)
+          ::Module.new(&block).tap do |anonymous|
+            document.send(:include, anonymous)
+            document.extend(anonymous.const_get(:ClassMethods)) if anonymous.const_defined?(:ClassMethods, false)
+          end
+        end
 
-      private_class_method :anonymous_document?, :include_anonymous, :normalize
+        def normalize(mod, document, block)
+          anonymous_document?(mod, block) ? [Undefined, mod] : [mod, document]
+        end
+      end
     end
   end
 end

data/lib/sevgi/graphics/version.rb

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

data/lib/sevgi/graphics.rb

@@ -14,15 +14,44 @@ require_relative "graphics/version"
 
 module Sevgi
   # SVG document builder and DSL namespace.
+  #
+  # A document profile controls root metadata and preambles; a {Canvas} controls
+  # physical size, margins, viewport, and viewBox. {Graphics.SVG} combines them
+  # into an element tree. Library code keeps that tree as an object until it
+  # explicitly renders, validates, saves, or exports it.
+  #
+  # @example Build and render a minimal SVG document
+  #   drawing = Sevgi::Graphics.SVG :minimal, width: 10, height: 10 do
+  #     circle cx: 5, cy: 5, r: 4
+  #   end
+  #   drawing.Render #=> "<svg width=\"10\" height=\"10\">\n  <circle cx=\"5\" cy=\"5\" r=\"4\"/>\n</svg>"
+  # @see https://sevgi.roktas.dev/svg/ SVG construction and profile guide
+  # @see https://sevgi.roktas.dev/library-mode/ Library composition guide
+  # @see https://sevgi.roktas.dev/showcase/ Runnable drawing examples
+  # @see Sevgi::Graphics::Document
+  # @see Sevgi::Graphics::Canvas
   module Graphics
-    # @overload canvas(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 canvas(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
+    #   @raise [Sevgi::ArgumentError] when the paper or an override is invalid
+    # @overload canvas(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
+    # @example Use the component constructor in library code
+    #   page = Sevgi::Graphics.canvas(:a4, margins: [12, 10])
+    #   icon = Sevgi::Graphics.canvas(width: 24, height: 24, unit: :px)
+    #   [page.name, icon.viewport] # => [:a4, {width: "24.0px", height: "24.0px"}]
     def canvas(...)
-      Graphics::Canvas.from_paper(...)
+      Graphics::Canvas.call(...)
     end
 
     # @overload document(name)
@@ -34,8 +63,10 @@ module Sevgi
     #   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.
+    #   process-global, thread-atomic registry; attribute names and nested Hash keys are normalized, nil attributes are
+    #   omitted, update suffixes are retained for document-class inheritance, and mutable non-container 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
@@ -48,12 +79,25 @@ module Sevgi
     #   @return [Class] anonymous document class
     #   @raise [Sevgi::ArgumentError] when metadata is invalid XML, cyclic, or cannot be stringified
     # @return [Class] document class
+    # @example Define, look up, and inspect a named document
+    #   Sevgi::Graphics.document(:card, attributes: {viewBox: "0 0 100 60"})
+    #   Sevgi::Graphics::Document.fetch(:card)              # => the registered document class
+    #   Sevgi::Graphics::Document.profile(:card).attributes # => {viewBox: "0 0 100 60"}
+    # @example Define an anonymous document without changing the registry
+    #   klass = Sevgi::Graphics.document(attributes: {viewBox: "0 0 10 10"})
+    #   klass.profile.name # => nil
+    # @example Define and use a named profile from library code
+    #   Sevgi::Graphics.document(:badge, attributes: {viewBox: "0 0 24 24"})
+    #   drawing = Sevgi::Graphics.SVG(:badge) { circle cx: 12, cy: 12, r: 10 }
+    #   drawing[:viewBox] # => "0 0 24 24"
     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.
+    # Use the non-bang {#document} for ordinary idempotent definitions; this
+    # bang form is an explicit process-global replacement.
     # @param name [Symbol, String] profile name
     # @param preambles [Array<String>, nil] document preamble lines
     # @param attributes [Hash, nil] default root attributes; nil means an empty Hash
@@ -78,6 +122,7 @@ module Sevgi
     end
 
     # Defines or replaces a paper profile.
+    # Use this only when replacing the process-global meaning of a name is intentional.
     # @param width [Numeric] paper width
     # @param height [Numeric] paper height
     # @param name [Symbol, String] profile name
@@ -85,10 +130,13 @@ module Sevgi
     # @return [Symbol, String] original profile name
     # @raise [Sevgi::ArgumentError] when the profile is invalid or the profile name is reserved
     def paper!(width, height, name = :custom, unit: "mm")
-      name.tap { Graphics::Paper.define(name, width:, height:, unit:) }
+      name.tap { Graphics::Paper.define(name, width:, height:, unit:, overwrite: true) }
     end
 
-    # Builds an SVG root document.
+    # Builds an SVG root element tree without rendering it.
+    #
+    # The first argument selects root metadata; the second supplies physical
+    # canvas attributes. Keyword attributes are applied to the root after both.
     # @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
     # @yield evaluates the drawing DSL in the root element
@@ -102,6 +150,4 @@ module Sevgi
     extend self
   end
 
-  # Top-level alias for the graphics DSL namespace.
-  SVG = Graphics
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sevgi-graphics
 version: !ruby/object:Gem::Version
-  version: 0.95.0
+  version: 0.98.2
 platform: ruby
 authors:
 - Recai Oktaş
@@ -15,15 +15,15 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.95.0
+        version: 0.98.2
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.95.0
-description: Provides an extensible DSL for creating SVG content.
+        version: 0.98.2
+description: Builds and renders SVG document trees from Ruby.
 email: roktas@gmail.com
 executables: []
 extensions: []
@@ -39,6 +39,7 @@ files:
 - lib/sevgi/graphics/auxiliary/content.rb
 - lib/sevgi/graphics/auxiliary/margin.rb
 - lib/sevgi/graphics/auxiliary/paper.rb
+- lib/sevgi/graphics/auxiliary/path.rb
 - lib/sevgi/graphics/auxiliary/scalar.rb
 - lib/sevgi/graphics/auxiliary/sizes.rb
 - lib/sevgi/graphics/document.rb
@@ -92,7 +93,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.11
+rubygems_version: 4.0.16
 specification_version: 4
-summary: Core DSL for the Sevgi toolkit.
+summary: Core SVG DSL for Sevgi.
 test_files: []