sevgi-graphics 0.95.0 → 0.98.2

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

@@ -4,48 +4,72 @@ 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
 
@@ -64,17 +88,24 @@ module Sevgi
       # @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
-      # @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]
+      # @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
@@ -82,22 +113,48 @@ module Sevgi
 
       # @overload attributes(origin = Undefined)
       #   Returns SVG root viewport attributes.
-      #   @param origin [Numeric, Array<Numeric>, nil, Sevgi::Undefined] viewBox origin
+      #   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{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
@@ -108,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?
 

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

@@ -2,10 +2,38 @@
 
 module Sevgi
   module Graphics
-    # 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.
+    # 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
+      private_class_method :new
+
       # Immutable payload capture and caller-owned copy helpers.
       # @api private
       module Snapshot
@@ -84,6 +112,7 @@ module Sevgi
       # @return [void]
       # @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)
@@ -98,13 +127,18 @@ module Sevgi
         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]
@@ -121,15 +155,7 @@ module Sevgi
       #   @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.
-      # 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) }
+      def self.cdata(...) = CData.send(:new, ...)
 
       # @overload css(content)
       #   Builds CSS content.
@@ -138,7 +164,7 @@ module Sevgi
       #   @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(...)
+      def self.css(...) = CSS.send(:new, ...)
 
       # @overload encoded(content)
       #   Builds XML text-encoded content.
@@ -147,12 +173,7 @@ module Sevgi
       #   @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.
-      # @param contents [Object, Array<Object>] content lines
-      # @return [String]
-      def self.text(contents) = Array(contents).join("\n")
+      def self.encoded(...) = Encoded.send(:new, ...)
 
       # @overload verbatim(content)
       #   Builds verbatim content.
@@ -161,7 +182,7 @@ module Sevgi
       #   @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(...)
+      def self.verbatim(...) = Verbatim.send(:new, ...)
 
       # CDATA section content backed by an immutable payload snapshot. Mutable leaf objects are stringified during
       # construction; embedded terminators are split during rendering.
@@ -169,9 +190,9 @@ module Sevgi
       class CData < Content
         # 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
 
@@ -195,6 +216,7 @@ module Sevgi
         # @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") unless content.is_a?(::Hash)
           validate_styles(content)
@@ -202,11 +224,10 @@ module Sevgi
           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]
+        # @return [Object] ignored by the rendering engine
         def render(renderer, depth)
           depth += 1
 
@@ -230,7 +251,6 @@ module Sevgi
 
           renderer.append(depth, "]]>")
         end
-        # rubocop:enable Metrics/MethodLength
 
         private
 
@@ -254,9 +274,9 @@ module Sevgi
         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
 
@@ -270,9 +290,9 @@ module Sevgi
         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

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

@@ -3,6 +3,19 @@
 module Sevgi
   module Graphics
     # Four-sided margin with CSS-like shorthand normalization.
+    # @!parse
+    #   class Margin
+    #     # Creates a margin from one to four CSS-like shorthand values.
+    #     # @param top [Numeric, nil] top value or all-sides shorthand
+    #     # @param right [Numeric, nil] right value or horizontal shorthand
+    #     # @param bottom [Numeric, nil] bottom value
+    #     # @param left [Numeric, nil] left value
+    #     # @return [Sevgi::Graphics::Margin]
+    #     # @raise [Sevgi::ArgumentError] when a supplied value is not a finite, non-negative real number
+    #     # @example Create a vertical and horizontal margin
+    #     #   Sevgi::Graphics::Margin[5, 10]
+    #     def self.[](top = nil, right = nil, bottom = nil, left = nil); end
+    #   end
     Margin = Data.define(:top, :right, :bottom, :left) do
       include Comparable
 
@@ -28,14 +41,17 @@ module Sevgi
       end
 
       # Compares margins by top, right, bottom, then left.
-      # @param other [Sevgi::Graphics::Margin] margin to compare
-      # @return [Integer, nil]
-      def <=>(other) = deconstruct <=> other.deconstruct
+      # @param other [Object] margin to compare
+      # @return [Integer, nil] comparison result, or nil for a non-Margin operand
+      def <=>(other)
+        deconstruct <=> other.deconstruct if other.is_a?(self.class)
+      end
 
       # Returns a margin inflated horizontally and vertically.
       # @param h [Numeric] horizontal addition
       # @param v [Numeric] vertical addition
       # @return [Sevgi::Graphics::Margin]
+      # @raise [Sevgi::ArgumentError] when the adjusted margin is negative or not finite
       def adjust(h, v) = self.class[top + v, right + h, bottom + v, left + h]
 
       # Reports strict margin equality.
@@ -61,15 +77,6 @@ module Sevgi
       # @return [Array<Float>]
       alias_method :to_a, :deconstruct
 
-      # Builds a margin from an array-like shorthand.
-      # @param array [Object] value converted with Array()
-      # @return [Sevgi::Graphics::Margin]
-      def self.margin(array)
-        self[
-          *(array = Array(array)[0...(size = Margin.members.size)]).fill(nil, array.size, size - array.size)
-        ]
-      end
-
       # Returns a zero margin.
       # @return [Sevgi::Graphics::Margin]
       def self.zero = (@zero ||= self[0.0, 0.0, 0.0, 0.0])

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

@@ -3,6 +3,19 @@
 module Sevgi
   module Graphics
     # Paper size and unit profile.
+    # @!parse
+    #   class Paper
+    #     # Creates a paper profile from dimensions and optional metadata.
+    #     # @param width [Numeric] paper width
+    #     # @param height [Numeric] paper height
+    #     # @param unit [Symbol, String] SVG unit
+    #     # @param name [Symbol, String] profile name
+    #     # @return [Sevgi::Graphics::Paper]
+    #     # @raise [Sevgi::ArgumentError] when dimensions, unit, or name are invalid
+    #     # @example Create a custom paper profile with value notation
+    #     #   Sevgi::Graphics::Paper[90, 50, :mm, :card]
+    #     def self.[](width, height, unit = "mm", name = :custom); end
+    #   end
     Paper = Data.define(:width, :height, :unit, :name) do
       include Comparable
 
@@ -71,10 +84,25 @@ module Sevgi
         name ? @mutex.synchronize { @profiles.key?(name) } : false
       end
 
+      # Returns a registered paper profile by name.
+      # @param name [Symbol, String] profile name, including names that are not Ruby identifiers
+      # @return [Sevgi::Graphics::Paper] registered profile
+      # @raise [Sevgi::ArgumentError] when name is invalid or no profile is registered
+      # @example Look up a non-identifier profile name
+      #   Sevgi::Graphics::Paper.define("business-card", width: 90, height: 50)
+      #   Sevgi::Graphics::Paper.fetch("business-card")
+      def self.fetch(name)
+        name = normalize!(:name, name)
+        @mutex.synchronize { @profiles.fetch(name) { ArgumentError.("Unknown paper profile: #{name}") } }
+      end
+
+      # Returns registered profile names.
+      # @return [Array<Symbol>] frozen name snapshot
+      def self.keys = @mutex.synchronize { @profiles.keys.freeze }
+
       # Defines a named paper profile after complete validation. Registration is process-global and thread-atomic.
-      # Existing profiles are replaced by default; with `overwrite: false`, identical definitions return the canonical
-      # profile and conflicting definitions raise. Names that are not Ruby call syntax remain accessible through
-      # `public_send`.
+      # Identical definitions return the canonical profile and conflicting definitions raise unless replacement is
+      # explicitly requested. Names that are not Ruby call syntax remain accessible through {.fetch}.
       # @param name [Symbol, String] profile name
       # @param overwrite [Boolean] true to replace an existing profile
       # @param spec [Hash] paper dimensions and unit
@@ -84,7 +112,11 @@ module Sevgi
       # @return [Sevgi::Graphics::Paper]
       # @raise [Sevgi::ArgumentError] when the name, dimensions, unit, overwrite flag, or options are reserved or invalid,
       #   or a non-bang definition conflicts with the registered profile
-      def self.define(name, overwrite: true, **spec)
+      # @example Define or reuse a matching profile
+      #   Sevgi::Graphics::Paper.define(:card, width: 90, height: 50)
+      # @example Replace a profile explicitly
+      #   Sevgi::Graphics::Paper.define(:card, width: 100, height: 60, overwrite: true)
+      def self.define(name, overwrite: false, **spec)
         name = normalize!(:name, name)
         ArgumentError.("Paper name is reserved: #{name}") if reserved?(name)
         overwrite = overwrite!(overwrite)
@@ -93,68 +125,61 @@ module Sevgi
         register(name, profile, overwrite:)
       end
 
-      def self.install(name)
-        return if @accessors.key?(name)
+      class << self
+        private
 
-        define_singleton_method(name) { @mutex.synchronize { @profiles.fetch(name) } }
-        @accessors[name] = true
-      end
+        def install(name)
+          return if @accessors.key?(name)
 
-      def self.register(name, profile, overwrite:)
-        @mutex.synchronize do
-          if !overwrite && (current = @profiles[name])
-            ArgumentError.("Paper already defined differently: #{name}") unless current == profile
+          define_singleton_method(name) { @mutex.synchronize { @profiles.fetch(name) } }
+          @accessors[name] = true
+        end
 
-            next current
-          end
+        def register(name, profile, overwrite:)
+          @mutex.synchronize do
+            if !overwrite && (current = @profiles[name])
+              ArgumentError.("Paper already defined differently: #{name}") unless current == profile
+
+              next current
+            end
 
-          install(name)
-          @profiles[name] = profile
+            install(name)
+            @profiles[name] = profile
+          end
         end
-      end
 
-      def self.reserved?(name) = @reserved.include?(name)
+        def reserved?(name) = @reserved.include?(name)
 
-      def self.dimension!(field, value)
-        Scalar.finite(value, context: "paper", field:, positive: true)
-      end
+        def dimension!(field, value)
+          Scalar.finite(value, context: "paper", field:, positive: true)
+        end
 
-      def self.options!(options)
-        return if options.empty?
+        def options!(options)
+          return if options.empty?
 
-        ArgumentError.("Unknown paper options: #{options.keys.join(", ")}")
-      end
+          ArgumentError.("Unknown paper options: #{options.keys.join(", ")}")
+        end
 
-      def self.overwrite!(value)
-        return value if [true, false].include?(value)
+        def overwrite!(value)
+          return value if [true, false].include?(value)
 
-        ArgumentError.("Paper overwrite must be true or false")
-      end
+          ArgumentError.("Paper overwrite must be true or false")
+        end
 
-      def self.normalize(value)
-        normalized = value.to_sym if value.respond_to?(:to_sym)
-        normalized if normalized.is_a?(::Symbol)
-      rescue ::StandardError
-        nil
-      end
+        def normalize(value)
+          normalized = value.to_sym if value.respond_to?(:to_sym)
+          normalized if normalized.is_a?(::Symbol)
+        rescue ::StandardError
+          nil
+        end
 
-      def self.normalize!(field, value)
-        normalize(value) || ArgumentError.("Invalid paper #{field}")
+        def normalize!(field, value)
+          normalize(value) || ArgumentError.("Invalid paper #{field}")
+        end
       end
 
       @reserved = methods.map(&:to_sym).freeze
 
-      private_class_method(
-        :dimension!,
-        :install,
-        :normalize,
-        :normalize!,
-        :options!,
-        :overwrite!,
-        :register,
-        :reserved?
-      )
-
       PAPER_SIZES.each { |name, (width, height, unit)| define(name, width:, height:, unit:) }
 
       # Returns the default paper profile.

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Sevgi
+  module Graphics
+    # Output path normalization shared by Graphics writers and exporters.
+    # @api private
+    module Path
+      # Converts a non-blank path to an expanded String.
+      # @param value [String, #to_path] raw path value
+      # @param context [String] public operation named in errors
+      # @return [String] expanded path
+      # @raise [Sevgi::ArgumentError] when value is blank, has an invalid type, or path conversion fails
+      def self.call(value, context:)
+        path = value.respond_to?(:to_path) ? value.to_path : value
+        ArgumentError.("#{context} must be a String or path-like object") unless path.is_a?(::String)
+        ArgumentError.("#{context} must be provided") if path.strip.empty?
+
+        ::File.expand_path(path)
+      rescue ::Sevgi::ArgumentError
+        raise
+      rescue ::StandardError => e
+        ArgumentError.("#{context} must be a String or path-like object: #{e.message}")
+      end
+
+      # Resolves an optional path with the writer/exporter directory convention.
+      # @param value [String, #to_path, nil] explicit path or directory
+      # @param default [String, #to_path] default output path
+      # @param context [String] public operation named in errors
+      # @return [String] expanded output file path
+      # @raise [Sevgi::ArgumentError] when a selected path/default is blank, invalid, or cannot be converted
+      def self.resolve(value, default:, context:)
+        return call(default, context: "#{context} default") if value.nil?
+
+        path = call(value, context: "#{context} path")
+        return path unless ::File.directory?(path)
+
+        default = call(default, context: "#{context} default")
+        ::File.join(path, ::File.basename(default))
+      end
+    end
+
+    private_constant :Path
+  end
+end