sevgi 0.95.0 → 0.98.2

data/lib/sevgi/toplevel/derender.rb

@@ -4,20 +4,106 @@ require "sevgi/derender"
 
 module Sevgi
   module Toplevel
+    # Converts inline SVG/XML content into a derender node.
+    # @param content [String] SVG/XML source content
+    # @param id [String, Symbol, nil] optional SVG id selecting a node inside the source
+    # @param omit [String, Symbol, Array<String, Symbol>, nil] exact attribute name or names omitted from the selected
+    #   subtree after id selection
+    # @return [Sevgi::Derender::Node] selected node in the derender tree
+    # @raise [Sevgi::ArgumentError] when content is malformed or rootless, or the id is absent
+    # @see Sevgi.Decompile
+    # @see Sevgi::Derender.decompile
+    def Decompile(content, id: nil, omit: nil) = Derender.decompile(content, id:, omit:)
+
     # Converts an SVG/XML file into a derender node.
     # @param file [String] path to the source SVG/XML file
-    # @param id [String, nil] optional SVG id selecting a node inside the source
+    # @param id [String, Symbol, nil] optional SVG id selecting a node inside the source
+    # @param omit [String, Symbol, Array<String, Symbol>, nil] exact attribute name or names omitted from the selected
+    #   subtree after id selection
     # @return [Sevgi::Derender::Node] selected node in the derender tree
-    # @raise [Sevgi::ArgumentError] when the file cannot be found or the id is absent
+    # @raise [Sevgi::ArgumentError] when the file is absent, malformed, or rootless, or the id is absent
+    # @raise [SystemCallError] when the file cannot be read
+    # @see Sevgi.DecompileFile
     # @see Sevgi::Derender.decompile_file
-    def Decompile(file, id = nil) = Derender.decompile_file(file, id:)
+    def DecompileFile(file, id: nil, omit: nil) = Derender.decompile_file(file, id:, omit:)
+
+    # Converts inline SVG/XML content into Sevgi DSL Ruby source.
+    # @param content [String] SVG/XML source content
+    # @param id [String, Symbol, nil] optional SVG id selecting a node inside the source
+    # @param omit [String, Symbol, Array<String, Symbol>, nil] exact attribute name or names omitted from the selected
+    #   subtree after id selection
+    # @return [String] formatted Sevgi DSL source
+    # @raise [Sevgi::ArgumentError] when content is malformed or rootless, or the id is absent
+    # @raise [Sevgi::PanicError] when generated Ruby source cannot be formatted
+    # @see Sevgi.Derender
+    # @see Sevgi::Derender.derender
+    def Derender(content, id: nil, omit: nil) = Derender.derender(content, id:, omit:)
 
     # Converts an SVG/XML file into Sevgi DSL Ruby source.
     # @param file [String] path to the source SVG/XML file
-    # @param id [String, nil] optional SVG id selecting a node inside the source
+    # @param id [String, Symbol, nil] optional SVG id selecting a node inside the source
+    # @param omit [String, Symbol, Array<String, Symbol>, nil] exact attribute name or names omitted from the selected
+    #   subtree after id selection
     # @return [String] formatted Sevgi DSL source
-    # @raise [Sevgi::ArgumentError] when the file cannot be found or the id is absent
+    # @raise [Sevgi::ArgumentError] when the file is absent, malformed, or rootless, or the id is absent
+    # @raise [Sevgi::PanicError] when generated Ruby source cannot be formatted
+    # @raise [SystemCallError] when the file cannot be read
+    # @see Sevgi.DerenderFile
     # @see Sevgi::Derender.derender_file
-    def Derender(file, id = nil) = Derender.derender_file(file, id:)
+    def DerenderFile(file, id: nil, omit: nil) = Derender.derender_file(file, id:, omit:)
+
+    # Evaluates inline SVG/XML content under a graphics element, including the selected node.
+    # @param content [String] SVG/XML source content
+    # @param element [Sevgi::Graphics::Element] target graphics element
+    # @param id [String, Symbol, nil] optional SVG id selecting a node inside the source
+    # @param omit [String, Symbol, Array<String, Symbol>, nil] exact attribute name or names omitted from the selected
+    #   subtree after id selection
+    # @return [Sevgi::Graphics::Element, nil] included selected/root element, or nil when it produces no output
+    # @raise [Sevgi::ArgumentError] when content is malformed or rootless, or the id is absent
+    # @see Sevgi.Evaluate
+    # @see Sevgi::Derender.evaluate
+    def Evaluate(content, element, id: nil, omit: nil) = Derender.evaluate(content, element, id:, omit:)
+
+    # Evaluates only the selected node's children from inline SVG/XML content under a graphics element.
+    # @param content [String] SVG/XML source content
+    # @param element [Sevgi::Graphics::Element] target graphics element
+    # @param id [String, Symbol, nil] optional SVG id selecting a node inside the source
+    # @param omit [String, Symbol, Array<String, Symbol>, nil] exact attribute name or names omitted from the selected
+    #   subtree after id selection
+    # @return [Array<Sevgi::Graphics::Element>] immutable included-child snapshot
+    # @raise [Sevgi::ArgumentError] when content is malformed or rootless, or the id is absent
+    # @see Sevgi.EvaluateChildren
+    # @see Sevgi::Derender.evaluate_children
+    def EvaluateChildren(content, element, id: nil, omit: nil)
+      Derender.evaluate_children(content, element, id:, omit:)
+    end
+
+    # Evaluates only the selected node's children from an SVG/XML file under a graphics element.
+    # @param file [String] path to the source SVG/XML file
+    # @param element [Sevgi::Graphics::Element] target graphics element
+    # @param id [String, Symbol, nil] optional SVG id selecting a node inside the source
+    # @param omit [String, Symbol, Array<String, Symbol>, nil] exact attribute name or names omitted from the selected
+    #   subtree after id selection
+    # @return [Array<Sevgi::Graphics::Element>] immutable included-child snapshot
+    # @raise [Sevgi::ArgumentError] when the file is absent, malformed, or rootless, or the id is absent
+    # @raise [SystemCallError] when the file cannot be read
+    # @see Sevgi.EvaluateChildrenFile
+    # @see Sevgi::Derender.evaluate_children_file
+    def EvaluateChildrenFile(file, element, id: nil, omit: nil)
+      Derender.evaluate_children_file(file, element, id:, omit:)
+    end
+
+    # Evaluates an SVG/XML file under a graphics element, including the selected node.
+    # @param file [String] path to the source SVG/XML file
+    # @param element [Sevgi::Graphics::Element] target graphics element
+    # @param id [String, Symbol, nil] optional SVG id selecting a node inside the source
+    # @param omit [String, Symbol, Array<String, Symbol>, nil] exact attribute name or names omitted from the selected
+    #   subtree after id selection
+    # @return [Sevgi::Graphics::Element, nil] included selected/root element, or nil when it produces no output
+    # @raise [Sevgi::ArgumentError] when the file is absent, malformed, or rootless, or the id is absent
+    # @raise [SystemCallError] when the file cannot be read
+    # @see Sevgi.EvaluateFile
+    # @see Sevgi::Derender.evaluate_file
+    def EvaluateFile(file, element, id: nil, omit: nil) = Derender.evaluate_file(file, element, id:, omit:)
   end
 end

data/lib/sevgi/toplevel/executor.rb

@@ -8,22 +8,61 @@ module Sevgi
   private_constant :BootBlock
 
   # Executes Sevgi script source with the full top-level DSL installed.
-  # @param args [Array] arguments forwarded to {Sevgi::Executor.execute}
-  # @param kwargs [Hash] keyword arguments forwarded to {Sevgi::Executor.execute}
-  # @return [Sevgi::Executor::Scope, nil] execution result, or nil for empty source
-  # @note Required-library load failures are captured as {Sevgi::Executor::Error} on the returned scope.
+  #
+  # @example Execute source in an isolated scope
+  #   result = Sevgi.execute("F.pluralize('cat')")
+  #   result.value # => "cats"
+  # @param string [String] source to evaluate
+  # @param file [String, nil] source file name used for errors and backtraces
+  # @param line [Integer, nil] starting source line used for errors and backtraces
+  # @param require [String, nil] optional Ruby library to require before execution
+  # @param main [Boolean] whether to install the DSL through Ruby's top-level main object
+  # @return [Sevgi::Executor::Result] immutable execution result
+  # @raise [Sevgi::ArgumentError] when source, file, line, required library, or main mode is invalid
+  # @note Script and required-library failures are captured in {Sevgi::Executor::Result#error}.
+  # @note The default isolated mode does not modify Ruby's top-level main object. `main: true` preserves the command-line
+  #   default by installing Sevgi through main before evaluating source in the managed script scope.
+  # @note Empty source without `require:` is a strict no-op; the DSL boot block is unused.
   # @note Reentrant and concurrent calls keep independent executor scope stacks per fiber.
-  # @see Sevgi::Executor.execute
-  def self.execute(*args, **kwargs) = Executor.execute(*args, **kwargs, &BootBlock)
+  # @see https://sevgi.roktas.dev/execution/ Execution guide
+  def self.execute(string, file: nil, line: nil, require: nil, main: false)
+    Executor.__send__(:execute, string, file:, line:, require:, receiver: execution_receiver(main), &BootBlock)
+  end
 
   # Executes a Sevgi script file with the full top-level DSL installed.
-  # @param args [Array] arguments forwarded to {Sevgi::Executor.execute_file}
-  # @param kwargs [Hash] keyword arguments forwarded to {Sevgi::Executor.execute_file}
-  # @return [Sevgi::Executor::Scope, nil] execution result, or nil for an empty file
-  # @note File-read and required-library load failures are captured as {Sevgi::Executor::Error} on the returned scope.
+  # @param file [String] source file to read and execute
+  # @param as [String, nil] source basename used for evaluation, diagnostics, and caller-derived output defaults;
+  #   its extension is replaced with `.sevgi` and the input file's directory is retained
+  # @param require [String, nil] optional Ruby library to require before execution
+  # @param main [Boolean] whether to install the DSL through Ruby's top-level main object
+  # @return [Sevgi::Executor::Result] immutable execution result
+  # @raise [Sevgi::ArgumentError] when file, logical source name, required library, or main mode is invalid
+  # @note File-read, script, and required-library failures are captured in {Sevgi::Executor::Result#error}.
+  # @note The default isolated mode does not modify Ruby's top-level main object. `main: true` preserves the command-line
+  #   default by installing Sevgi through main before evaluating source in the managed script scope.
+  # @note An empty file without `require:` is a strict no-op; the DSL boot block is unused.
   # @note Reentrant and concurrent calls keep independent executor scope stacks per fiber.
-  # @see Sevgi::Executor.execute_file
-  def self.execute_file(*args, **kwargs) = Executor.execute_file(*args, **kwargs, &BootBlock)
+  # @see https://sevgi.roktas.dev/execution/ Execution guide
+  def self.execute_file(file, as: nil, require: nil, main: false)
+    as = source_name(file, as) if as
+    Executor.__send__(:execute_file, file, as:, require:, receiver: execution_receiver(main), &BootBlock)
+  end
+
+  def self.execution_receiver(main)
+    ArgumentError.("Sevgi main mode must be true or false") unless [true, false].include?(main)
+
+    TOPLEVEL_BINDING.receiver if main
+  end
+
+  def self.source_name(file, name)
+    ArgumentError.("Sevgi file must be a String") unless file.is_a?(::String)
+    ArgumentError.("Sevgi file name must be a non-empty String") unless name.is_a?(::String) && !name.empty?
+    ArgumentError.("Sevgi file name must not include a directory") unless ::File.basename(name) == name
+
+    ::File.join(::File.dirname(file), F.subext(".sevgi", name))
+  end
+
+  private_class_method :execution_receiver, :source_name
 
   module Toplevel
     # Loads one or more Sevgi files relative to the caller's source file.
@@ -32,13 +71,16 @@ module Sevgi
     # @raise [Sevgi::PanicError] when called without an active executor scope
     # @raise [Sevgi::Error] when a file cannot be located
     # @note `Load` resolves against the active executor scope in the current fiber.
+    # @note Ordinary library code should use Ruby `require`; `Load` is available only during Sevgi script execution.
+    # @see Sevgi.Load
+    # @see Sevgi.execute_file
     def Load(*files)
       start = ::File.dirname(caller_locations(1..1).first.path)
 
       files.each do |file|
         location = F.locate(file, start)
 
-        ::Sevgi::Executor.load(location.file)
+        ::Sevgi::Executor.__send__(:load, location.file)
       end
     end
   end

data/lib/sevgi/toplevel/graphics.rb

@@ -4,14 +4,97 @@ require "sevgi/graphics"
 
 module Sevgi
   module Toplevel
+    # @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 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 Build a paper-backed canvas
+    #   canvas = Sevgi.Canvas :a4, margins: [12, 10]
+    # @see Sevgi.Canvas
+    # @see Sevgi::Graphics.canvas
+    def Canvas(...) = Graphics.canvas(...)
+
+    # @overload Document(name)
+    #   Looks up an existing document profile by name.
+    #   @param name [Symbol, String] profile name
+    #   @return [Class] document class
+    #   @raise [Sevgi::ArgumentError] when the profile is unknown
+    # @overload Document(name, preambles: Undefined, attributes: Undefined)
+    #   Defines or validates a named document profile.
+    #   @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
+    #   @return [Class] document class
+    #   @raise [Sevgi::ArgumentError] when a profile conflicts or metadata is invalid
+    # @overload Document(preambles: Undefined, attributes: Undefined)
+    #   Defines an anonymous document profile without registering it globally.
+    #   @param preambles [Array<String>, nil, Sevgi::Undefined] document preamble lines
+    #   @param attributes [Hash, nil, Sevgi::Undefined] default root attributes
+    #   @return [Class] anonymous document class
+    #   @raise [Sevgi::ArgumentError] when metadata is invalid
+    # @return [Class] document class
+    # @example Define and use a document profile
+    #   Sevgi.Document :icon, attributes: {viewBox: "0 0 24 24"}
+    #   drawing = Sevgi.SVG(:icon) { circle cx: 12, cy: 12, r: 10 }
+    # @see Sevgi.Document
+    # @see Sevgi::Graphics.document
+    def Document(...) = Graphics.document(...)
+
+    # Defines or replaces a document profile.
+    # @param name [Symbol, String] profile name
+    # @param preambles [Array<String>, nil] document preamble lines
+    # @param attributes [Hash, nil] default root attributes
+    # @return [Class] document class
+    # @raise [Sevgi::ArgumentError] when the name or metadata is invalid
+    # @see Sevgi.Document!
+    # @see Sevgi::Graphics.document!
+    def Document!(name, preambles: [], attributes: {})
+      Graphics.document!(name, preambles:, attributes:)
+    end
+
+    # Builds an SVG document through the full Sevgi top-level DSL.
+    # @param document [Symbol, String, Class] document profile name or document class
+    # @param canvas [Sevgi::Graphics::Canvas, Sevgi::Graphics::Paper, Symbol, String, Sevgi::Undefined, nil] optional
+    #   canvas or paper profile
+    # @param attributes [Hash] root SVG attributes
+    # @yield the document block evaluated in the SVG document context
+    # @yieldreturn [void]
+    # @return [Sevgi::Graphics::Document::Proto] SVG document object
+    # @raise [Sevgi::ArgumentError] when the document, paper, or canvas arguments are invalid
+    # @see Sevgi.SVG
+    # @see Sevgi::Graphics.SVG
+    def SVG(document = :default, canvas = Undefined, **attributes, &block)
+      Graphics.SVG(document, canvas, **attributes, &block)
+    end
+
+    # @overload Mixin(mod, document = Sevgi::Graphics::Document::Base)
+    #   Adds a named graphics mixture to a document class.
+    #   @param mod [Symbol, String] named mixture to mix into the document
+    #   @param document [Class] document class receiving the mixture
+    #   @return [nil]
+    #   @raise [NameError] when a named mixture cannot be resolved
+    #   @see Sevgi.Mixin
+    #   @see Sevgi::Graphics::Mixtures.mixin
     # @overload Mixin(mod, document = Sevgi::Graphics::Document::Base, &block)
-    #   Adds graphics mixture methods to a document class.
+    #   Adds a named graphics mixture and an anonymous extension to a document class.
     #   @param mod [Symbol, String] named mixture to mix into the document
     #   @param document [Class] document class receiving the mixture
     #   @yield optional anonymous mixture module body
     #   @yieldreturn [void]
-    #   @return [void]
+    #   @return [Module] anonymous mixture
     #   @raise [NameError] when a named mixture cannot be resolved
+    #   @see Sevgi.Mixin
     #   @see Sevgi::Graphics::Mixtures.mixin
     # @overload Mixin(document = Sevgi::Graphics::Document::Base, &block)
     #   Adds an anonymous graphics mixture to a document class.
@@ -20,6 +103,7 @@ module Sevgi
     #   @yieldreturn [void]
     #   @return [Module] anonymous mixture
     #   @raise [Sevgi::ArgumentError] when no named mixture or block is given
+    #   @see Sevgi.Mixin
     #   @see Sevgi::Graphics::Mixtures.mixin
     def Mixin(...) = Graphics::Mixtures.mixin(...)
 
@@ -27,10 +111,11 @@ module Sevgi
     #   Defines or validates a named paper profile for DSL use.
     #   @param width [Numeric] paper width
     #   @param height [Numeric] paper height
-    #   @param name [Symbol] paper profile name
+    #   @param name [Symbol, String] paper profile name
     #   @param unit [String, Symbol] size unit
-    #   @return [Symbol] the paper profile name
+    #   @return [Symbol, String] the original paper profile name
     #   @raise [Sevgi::ArgumentError] when the profile is invalid or an existing profile differs
+    #   @see Sevgi.Paper
     #   @see Sevgi::Graphics#paper
     def Paper(...) = Graphics.paper(...)
 
@@ -38,10 +123,11 @@ module Sevgi
     #   Defines or overwrites a named paper profile for DSL use.
     #   @param width [Numeric] paper width
     #   @param height [Numeric] paper height
-    #   @param name [Symbol] paper profile name
+    #   @param name [Symbol, String] paper profile name
     #   @param unit [String, Symbol] size unit
-    #   @return [Symbol] the paper profile name
+    #   @return [Symbol, String] the original paper profile name
     #   @raise [Sevgi::ArgumentError] when the profile is invalid or the paper name is reserved
+    #   @see Sevgi.Paper!
     #   @see Sevgi::Graphics#paper!
     def Paper!(...) = Graphics.paper!(...)
   end

data/lib/sevgi/toplevel/sundries.rb

@@ -4,7 +4,12 @@ require "sevgi/sundries"
 
 module Sevgi
   module Toplevel
-    # Builds a drawable grid from a graphics canvas.
+    # Builds a drawable grid fitted inside a graphics canvas.
+    #
+    # The canvas margins are minimum clearances. Any span left after fitting
+    # whole major intervals is shared equally between the opposite margins, so
+    # their requested difference is preserved. The returned grid starts at
+    # `(0, 0)`; {Sevgi::Sundries::Grid#canvas} exposes the fitted page margins.
     # @param canvas [Sevgi::Graphics::Canvas] canvas defining page size and margins
     # @param unit [Numeric] minor grid unit
     # @param multiple [Integer] number of minor units in each major interval
@@ -13,13 +18,16 @@ module Sevgi
     # @raise [Sevgi::ArgumentError] when unit is not a finite positive number
     # @raise [Sevgi::ArgumentError] when multiple is not a positive integer
     # @raise [Sevgi::ArgumentError] when canvas dimensions, margins, and grid intervals cannot fit
+    # @see Sevgi.Grid
+    # @see Sevgi::Sundries::Grid
     def Grid(canvas, unit:, multiple:)
       ArgumentError.("Must be a Canvas: #{canvas}") unless canvas.is_a?(Graphics::Canvas)
 
-      Sundries::Grid[
-        Sundries::Ruler.new(brut: canvas.width, unit:, multiple:, margin: canvas.left),
-        Sundries::Ruler.new(brut: canvas.height, unit:, multiple:, margin: canvas.top)
-      ]
+      Sundries::Grid.new(
+        x: Sundries::Ruler.new(brut: canvas.width, unit:, multiple:, margins: [canvas.left, canvas.right]),
+        y: Sundries::Ruler.new(brut: canvas.height, unit:, multiple:, margins: [canvas.top, canvas.bottom]),
+        canvas:
+      )
     end
 
     promote Sundries::Export

data/lib/sevgi/toplevel.rb

@@ -7,21 +7,19 @@ module Sevgi
   # normally be included directly.
   #
   # @see Sevgi
+  # @see https://sevgi.roktas.dev/library-mode/ Library mode guide
+  # @see https://sevgi.roktas.dev/script-mode/ Script mode guide
   module Toplevel
-    @constants = {}
+    @promotions = {}
 
     class << self
-      # Returns an immutable snapshot of promoted constants.
-      # @return [Hash<Symbol, Object>]
-      def constants = @constants.dup.freeze
-
       private
 
       def inject(base)
         return if base.instance_variable_defined?("@_toplevel_injected_")
 
         if base.is_a?(::Module)
-          @constants.each do |name, constant|
+          @promotions.each do |name, constant|
             base.const_set(name, constant) unless base.const_defined?(name, false)
           end
         end
@@ -30,7 +28,7 @@ module Sevgi
       end
 
       def promote(constant, symbol = Undefined)
-        @constants[Undefined.default(symbol, constant.to_s.split("::").last.to_sym)] = constant
+        @promotions[Undefined.default(symbol, constant.to_s.split("::").last.to_sym)] = constant
       end
     end
 
@@ -53,6 +51,8 @@ module Sevgi
       super
       inject(base)
     end
+
+    private_class_method :extended, :included
   end
 
   extend Toplevel

data/lib/sevgi/version.rb

@@ -2,5 +2,5 @@
 
 module Sevgi
   # Current version of the Sevgi top-level gem.
-  VERSION = "0.95.0"
+  VERSION = "0.98.2"
 end

data/lib/sevgi.rb

@@ -9,36 +9,121 @@ require "sevgi/sundries"
 
 require "sevgi/version"
 
-# Minimal top-level SVG interface installed by `require "sevgi"`.
-# @return [Module] the graphics module used as the SVG DSL namespace
-SVG = Sevgi::Graphics
+require_relative "sevgi/toplevel"
+require_relative "sevgi/svg"
+
+# SVG-domain facade installed by `require "sevgi"`.
+# @return [Module] the public SVG operations and types
+SVG = Sevgi::SVG
 
 # @overload SVG(document = :default, canvas = Undefined, **attributes, &block)
 #   Builds an SVG document through the default top-level DSL entrypoint.
-#   @param document [Symbol, Class] document profile name or document class
-#   @param canvas [Object] optional canvas or paper profile argument
+#   @param document [Symbol, String, Class] document profile name or document class
+#   @param canvas [Sevgi::Graphics::Canvas, Sevgi::Graphics::Paper, Symbol, String, Sevgi::Undefined, nil] optional
+#     canvas or paper profile
 #   @param attributes [Hash] root SVG attributes
 #   @yield the document block evaluated in the SVG document context
 #   @yieldreturn [void]
 #   @return [Sevgi::Graphics::Document::Proto] a rendered SVG document object
 #   @raise [Sevgi::ArgumentError] when the document, paper, or canvas arguments are invalid
-def SVG(...) = Sevgi::Graphics.SVG(...)
+# @example Build through the global library entrypoint
+#   SVG(:minimal) { circle r: 4 }.Render
+# @see Sevgi.SVG
+# @see Sevgi::Toplevel#SVG
+def SVG(...) = Sevgi.SVG(...)
 
 # Full top-level API for Sevgi library and script consumers.
 #
-# Including this module in a class or module installs DSL methods such as
-# `Paper`, `Load`, and `Grid`, plus convenience constants such as `F`,
-# `Geometry`, `Origin`, and `Export`. Extending a module does the same.
-# Extending an ordinary object installs the methods only and does not write
-# promoted constants to `Object`.
+# `require "sevgi"` installs the global document builder `SVG(...)` and the independent {Sevgi::SVG} facade. SVG-domain
+# operations use capitalized method names on that facade, such as `SVG.Canvas`, `SVG.Paper`, and `SVG.Derender`; types
+# and namespaces use Ruby's double-colon notation, such as `SVG::Canvas`. The same operations are available on `Sevgi`
+# for consumers that prefer the full toolkit namespace. Process-level operations such as {Sevgi.execute} remain on
+# `Sevgi` rather than the SVG facade.
+#
+# Including this module in a class or module installs the DSL methods plus convenience constants `F`, `Geometry`,
+# `Origin`, and `Export`; script execution provides the same promoted scope. Extending a module does the same. Extending
+# an ordinary object installs methods only and does not write promoted constants to `Object`. Focused component requires
+# expose their namespaced component APIs instead of this full top-level surface.
+#
+# `Load` is meaningful only during {Sevgi.execute}, {Sevgi.execute_file}, or command-line script execution. It resolves
+# nested `.sevgi` files through the active executor scope; it is not a general-purpose replacement for Ruby `require`.
 #
 # @example Include the DSL in an object
 #   class Drawing
 #     include Sevgi
 #   end
+# @see https://sevgi.roktas.dev/library-mode/ Library mode guide
+# @see https://sevgi.roktas.dev/script-mode/ Script mode guide
+# @see https://sevgi.roktas.dev/execution/ Embedded execution guide
 module Sevgi
-  # See sevgi/toplevel/*.rb files for details
-  require_relative "sevgi/toplevel"
+  # @!method self.Canvas(...)
+  #   Builds a canvas from a paper profile or explicit dimensions.
+  #   @return [Sevgi::Graphics::Canvas] canvas value
+  #   @see Sevgi::Toplevel#Canvas
+  # @!method self.Document(...)
+  #   Defines, validates, or looks up a document profile.
+  #   @return [Class] document class
+  #   @see Sevgi::Toplevel#Document
+  # @!method self.Document!(...)
+  #   Defines or replaces a document profile.
+  #   @return [Class] document class
+  #   @see Sevgi::Toplevel#Document!
+  # @!method self.SVG(...)
+  #   Builds an SVG document through the explicit namespaced top-level API.
+  #   @return [Sevgi::Graphics::Document::Proto] SVG document object
+  #   @see Sevgi::Toplevel#SVG
+  # @!method self.Mixin(...)
+  #   Extends a document profile with a named or anonymous graphics mixture.
+  #   @return [Module, nil] anonymous mixture when supplied, otherwise nil
+  #   @see Sevgi::Toplevel#Mixin
+  # @!method self.Paper(...)
+  #   Defines or validates a named paper profile.
+  #   @return [Symbol, String] original paper profile name
+  #   @see Sevgi::Toplevel#Paper
+  # @!method self.Paper!(...)
+  #   Defines or overwrites a named paper profile.
+  #   @return [Symbol, String] original paper profile name
+  #   @see Sevgi::Toplevel#Paper!
+  # @!method self.Grid(...)
+  #   Fits a drawable grid to a graphics canvas.
+  #   @return [Sevgi::Sundries::Grid] fitted grid
+  #   @see Sevgi::Toplevel#Grid
+  # @!method self.Decompile(...)
+  #   Converts inline SVG/XML into an immutable Derender node.
+  #   @return [Sevgi::Derender::Node] selected node
+  #   @see Sevgi::Toplevel#Decompile
+  # @!method self.DecompileFile(...)
+  #   Converts an SVG/XML file into an immutable Derender node.
+  #   @return [Sevgi::Derender::Node] selected node
+  #   @see Sevgi::Toplevel#DecompileFile
+  # @!method self.Derender(...)
+  #   Converts inline SVG/XML into formatted Sevgi DSL source.
+  #   @return [String] formatted Sevgi DSL source
+  #   @see Sevgi::Toplevel#Derender
+  # @!method self.DerenderFile(...)
+  #   Converts an SVG/XML file into formatted Sevgi DSL source.
+  #   @return [String] formatted Sevgi DSL source
+  #   @see Sevgi::Toplevel#DerenderFile
+  # @!method self.Evaluate(...)
+  #   Includes an inline SVG/XML node under a graphics element.
+  #   @return [Sevgi::Graphics::Element, nil] included element, or nil when no output is produced
+  #   @see Sevgi::Toplevel#Evaluate
+  # @!method self.EvaluateFile(...)
+  #   Includes an SVG/XML file node under a graphics element.
+  #   @return [Sevgi::Graphics::Element, nil] included element, or nil when no output is produced
+  #   @see Sevgi::Toplevel#EvaluateFile
+  # @!method self.EvaluateChildren(...)
+  #   Includes only an inline SVG/XML node's children under a graphics element.
+  #   @return [Array<Sevgi::Graphics::Element>] immutable included-child snapshot
+  #   @see Sevgi::Toplevel#EvaluateChildren
+  # @!method self.EvaluateChildrenFile(...)
+  #   Includes only an SVG/XML file node's children under a graphics element.
+  #   @return [Array<Sevgi::Graphics::Element>] immutable included-child snapshot
+  #   @see Sevgi::Toplevel#EvaluateChildrenFile
+  # @!method self.Load(...)
+  #   Loads nested `.sevgi` files through the active executor scope.
+  #   @return [Array<String>] requested file names
+  #   @see Sevgi::Toplevel#Load
 
   # Installs the full toplevel DSL into an including class or module.
   # @param base [Module] the class or module receiving the DSL methods
@@ -58,4 +143,6 @@ module Sevgi
     super
     base.extend(Toplevel)
   end
+
+  private_class_method :extended, :included
 end