sevgi 0.98.2 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 637d6a0c7a281ad8f1800c9fcf08968266c0e6c6a73a0ad6206a7b41e5c57fc5
-  data.tar.gz: b01598c764d715a4b381a90a3a6d5de203695459147142575cbd326ce176a07b
+  metadata.gz: 27a50b6890ad4f1ae6f47470e8b79896ad1281e2bdb54b7cfabd8310cd683c45
+  data.tar.gz: 7839ad48af80ceffb800314422b942406cb4bed1b7bb5c13e2774d121d0746ca
 SHA512:
-  metadata.gz: e0c7c633c134254b8eedd6f9d8da45530f4485b0e0b3508ce1e4b76522eca83d3de456a53e956cdba3c38f48fd38e811db70d25b3fb8ed44f4c6c0261319b500
-  data.tar.gz: b9182c6a0a4d250d0f1947bcf3b8c9e7b3bcebe9268e581d59cb2db4230315eadcf511e6880bd388a74847f441bbf5b0fcf4e37889ddfbc8c7ee7094e124a971
+  metadata.gz: 53837c04457e0ea48aa71642ea1c25a6fc352ba737b09dc073f988b4694d9cab561699695e6e2e6e89248a1704ccc659f4009e8aa4396737f7dc5a4b7b2ff5e3
+  data.tar.gz: 7f1ffa5979ce5af033451baf13c8746002f719782b633a4af16856d6283f828390eefb92bc2d17fdfbfa387f8e8e2675980dec86b992a483d17db35bdd56552d

data/CHANGELOG.md

@@ -3,7 +3,101 @@
 This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html) and follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
-## Unreleased
+## 1.0.0 - 2026-09-16
+
+### Added
+
+- Added Hatch and Orb Showcase examples and displayed both arc lengths in the Arc example.
+
+### Changed
+
+- Matched documentation page widths to the homepage Showcase.
+- Aligned Derender user guidance with UTF-8 normalization and safe subtree selection rules.
+- Clarified the packaged skill's script invocation, subtree copying, and Derender selection and encoding rules.
+- Allowed Canvas and Paper values as the first `SVG` argument when using the default document profile.
+- Made element `dup` and `clone` own independent subtrees while retaining IDs and Ruby copy semantics.
+- Made Segment equality compare length and direction; ordering still compares length only.
+- Limited Tile cell, row, and column queries to the requested geometry and accelerated XML character validation.
+- Simplified the first-run guide and aligned library constructor examples.
+- Updated the packaged skill for canvas origins, alignment, Paper lookup, curved geometry, and export constraints.
+- Revised DSL catalog examples and packaged Sevgi skill guidance to use statement-style calls and show inspection results.
+- Refined Showcase example tabs, made Ruby and XML views fill their panels, and hid executable preambles from Ruby views.
+- Documented non-rendering element data and clarified the related DSL catalog examples.
+- Refined Showcase heading spacing, page-title colors, and DSL catalog cards across light and dark themes.
+- Removed an obsolete ruler example and unused site code.
+- Kept the Squared and Copperplate guidesheet examples together at the end of the Showcase.
+- Updated the packaged skill to avoid duplicate semantic shapes and unnecessary paint passes.
+
+### Fixed
+
+- Kept horizontal scrollbars visible in Showcase example code panels.
+- Read Derender input in its declared XML encoding and normalized generated source, XML declarations, and markup to UTF-8.
+- Preserved open-path endpoints and derived edges independently of display precision.
+- Kept near-axis and near-parallel line equations and intersections independent of angle and slope rounding.
+- Corrected the Showcase social image dimensions.
+- Added SVG namespaces to standalone drawing examples and regenerated their outputs.
+- Made failed Sevgi Rake tasks stop dependent tasks and captured required-library failures in executor results.
+- Removed executor signal-handler replacement so the host and shell retain SIGINT ownership.
+- Escaped late export CSS as XML text and inserted it only at a supported final root closing tag.
+- Preserved Derender processing instructions and rejected custom entity references and unsupported trailing document nodes before inclusion.
+- Included both box origins in `Align`, unified Tile index validation, and isolated custom numeric attribute snapshots.
+- Prevented avoidable overflow and underflow in point distances.
+- Corrected browser source-panel expectations and added executable documentation, YARD, and packaged-skill checks.
+- Rendered inline code in DSL catalog summaries and kept linked task themes visible below the sticky header.
+- Restored Showcase tab icons with embedded Font Awesome SVGs.
+
+## 0.100.0 - 2026-09-09
+
+### Added
+
+- Added `ArcTo` and `ArcBy` for SVG-native elliptical arc paths.
+- Added Geometry `Arc`, `Ellipse`, and `Circle` with bounds, length, predicates, affine transformations, and
+  linear/quadratic intersections. Closed ellipses and circles support sweeps and hatching.
+- Added Geometry `Point.midpoint`, `Element#closed?`, lined `vertices`, open-path traversal, and `Rect#center`.
+- Added Geometry aggregate bounding boxes through `Operation.box`, point collinearity through `Point.collinear?`, and
+  polygon `simple?`, `convex?`, and `concave?` predicates.
+- Added Protractor and Arc examples and documented the drawing and calculation APIs.
+
+### Changed
+
+- Removed redundant parent scans while duplicating element subtrees.
+- Reused source bounds across Tile cells to reduce repeated calculations and object allocations.
+
+### Fixed
+
+- Preserved Showcase card HTML through Markdown rendering so all examples and their tabs remain visible.
+- Preserved XML declarations, pre-root comments, CDATA sections, inline comments, and namespace-only leaves in
+  Derender output and evaluation.
+- Limited PDF stamp recoloring to replaced text and carried graphics state across a page's content streams.
+- Corrected decimal interval fitting and made Grid point queries honor the active numeric precision.
+- Prevented implicit shell interpretation of single executable arguments in `F.sh` and `F.sh!`, including paths with spaces or shell metacharacters.
+- Preserved inherited namespaces on detached Derender nodes in generated source and direct evaluation, including imports through `EvaluateChildren` and `IncludeChildren`.
+- Prevented sweep and Hatch lines from crossing the exterior between two tangent vertices of a concave polygon.
+- Aligned Tile cells with their declared bounds for circles, rotated shapes, and polygons whose first vertex differs from their bounding-box origin.
+- Limited `Load` chains to 128 active sources with `Executor::LoadDepthError`, preserving cycle detection and nested load diagnostics.
+- Rejected nil and false aggregate-box inputs with the documented geometry error.
+- Restored precision-aware rejection of zero-length Triangle sides.
+- Made point-set collinearity independent of input order and removed eager polygon edge-pair storage.
+- Applied the collinearity tolerance to every three-point subset, removing coordinate-axis-dependent baseline selection.
+
+## 0.99.0 - 2026-08-09
+
+### Added
+
+- Added `SVG.Module` for building anonymous callable drawing modules with their contract installed before definition.
+- Added responsive Mermaid diagrams for the Derender round trip and SVG validation lifecycle.
+
+### Changed
+
+- Reorganized the documentation around getting started, usage, composition, documents, layout, output, and examples.
+- Documented how the `igves` and `igsev` command names reflect their conversion directions.
+- Normalized DSL catalog provider labels to lowercase and simplified polyfill-backed editor entries to `inkscape`.
+
+### Fixed
+
+- Allowed A5-on-A4 pdfcpu conversion to replace an existing output file.
+- Pre-rendered Mermaid diagrams as inline SVG instead of parsing them in site visitors' browsers.
+- Removed duplicate provider and context labels from DSL catalog entries.
 
 ## 0.98.2 - 2026-07-25
 
@@ -212,7 +306,7 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ### Changed
 
-- Added the checker board example to the documentation showcase flow.
+- Added the checkerboard example to the documentation showcase flow.
 - Consolidated Victor Book attribution for adapted showcase examples into a single documentation note.
 
 ### Fixed

data/README.md

@@ -30,7 +30,7 @@ igsev drawing.svg
 ```
 
 Both commands read standard input when the file is omitted or `-`. For `sevgi`, implicit `Save`, `PDF`, and `PNG`
-destinations use `output` as the input name; use `--as NAME` to choose another basename:
+destinations use `output` as the input name. Use `--as NAME` to choose another basename:
 
 ```sh
 sevgi --as badge < drawing.sevgi

data/lib/sevgi/binaries/rake.rb

@@ -16,13 +16,18 @@ module FileUtils
   # @param kwargs [Hash] keyword arguments exposed to the script as `ARGH`
   # @return [Sevgi::Executor::Result] immutable execution result
   # @raise [Sevgi::ArgumentError] when the script file cannot be found
+  # @raise [Sevgi::Executor::Error] when execution fails, so Rake stops dependent tasks
   # @see Sevgi.execute_file
   def sevgi(file, *args, **kwargs)
-    Sevgi::Executor.__send__(:execute_file, Sevgi::F.existing!(file, [Sevgi::EXTENSION])) do
+    result = Sevgi::Executor.__send__(:execute_file, Sevgi::F.existing!(file, [Sevgi::EXTENSION])) do
       extend(Sevgi)
 
       const_set(:ARGA, args).freeze
       const_set(:ARGH, kwargs).freeze
     end
+
+    raise result.error if result.error?
+
+    result
   end
 end

data/lib/sevgi/binaries/sevgi.rb

@@ -83,7 +83,7 @@ module Sevgi
         return puts(::Sevgi::VERSION) if options.version
 
         file = operand(argv)
-        handle(run(file, options), file, options)
+        handle(run(file, options), options)
 
       rescue Skill::Error => e
         abort(e.message)
@@ -93,17 +93,18 @@ module Sevgi
 
       private
 
-      def die(error, _file)
-        warn(error.message, "", *error.load_backtrace.map { "  #{it}" })
+      def die(error)
+        message = error.message.empty? ? error.cause.class.to_s : error.message
+        warn(message, "", *error.load_backtrace.map { "  #{it}" })
         exit(1)
       end
 
-      def handle(result, file, options)
+      def handle(result, options)
         return unless result&.error?
 
         raise result.error if options.vomit || ENV[ENVVOMIT]
 
-        die(result.error, file)
+        die(result.error)
       end
 
       def help

data/lib/sevgi/executor/error.rb

@@ -3,17 +3,25 @@
 module Sevgi
   class Executor
     # Raised when a source attempts to load another source already active in the same scope.
-    # @see https://sevgi.roktas.dev/execution/ Execution guide
+    # @see https://sevgi.roktas.dev/usage/#execute Execute source guide
     class CycleError < ::Sevgi::Error
     end
 
+    # Raised when nested Sevgi loads exceed the executor's supported active-source depth.
+    #
+    # The limit is 128 active sources, including the entry source. It does not count Ruby stack frames
+    # or guarantee protection from stack exhaustion within scripts.
+    # @see https://sevgi.roktas.dev/usage/#execute Execute source guide
+    class LoadDepthError < ::Sevgi::Error
+    end
+
     # Wraps an exception raised while executing Sevgi script source. Its visited source snapshot records every source in
-    # load order; it is not the active load stack at the instant of failure.
-    # @see https://sevgi.roktas.dev/execution/ Execution guide
+    # load order. It is not the active load stack at the instant of failure.
+    # @see https://sevgi.roktas.dev/usage/#execute Execute source guide
     class Error < ::Sevgi::Error
       # Builds an executor error wrapper.
       # @param error [Exception] original exception
-      # @param stack [Array<String>] source file keys visited in load order; the Array and its String entries are copied
+      # @param stack [Array<String>] source file keys visited in load order. The Array and its String entries are copied
       #   and frozen
       # @return [void]
       def initialize(error, stack)

data/lib/sevgi/executor/result.rb

@@ -5,9 +5,9 @@ module Sevgi
     # Describes the outcome of one executor invocation.
     #
     # A successful result has a value and no error. A captured script, file, or
-    # library failure has an {Executor::Error} and may retain a value produced
+    # library failure has an {Executor::Error} and can retain a value produced
     # before the failure. The source stack is an immutable snapshot in load
-    # order; it is never shared with the executor's internal mutable state.
+    # order. It is never shared with the executor's internal mutable state.
     #
     # @example Inspect successful execution
     #   result = Sevgi.execute("6 * 7")
@@ -22,7 +22,7 @@ module Sevgi
     #
     # @see Sevgi.execute
     # @see Sevgi.execute_file
-    # @see https://sevgi.roktas.dev/execution/ Execution guide
+    # @see https://sevgi.roktas.dev/usage/#execute Execute source guide
     Result = Data.define(:value, :error, :stack) do
       # @!attribute [r] value
       #   @return [Object, nil] last value produced, or nil when no value was produced

data/lib/sevgi/executor/scope.rb

@@ -8,6 +8,9 @@ module Sevgi
     # fiber's executor stack. They are not shared between concurrent executions.
     # @api private
     class Scope
+      MAX_LOAD_DEPTH = 128
+      private_constant :MAX_LOAD_DEPTH
+
       # @!attribute [r] scope
       #   @return [Module] isolated module where script source is evaluated
       # @!attribute [r] recent
@@ -115,8 +118,13 @@ module Sevgi
       end
 
       def enter(source)
-        if @active.key?(source.identity)
-          raise Executor::CycleError, "Recursive Sevgi load: #{source.file}"
+        raise Executor::CycleError, "Recursive Sevgi load: #{source.file}" if @active.key?(source.identity)
+
+        if @active.size >= MAX_LOAD_DEPTH
+          raise(
+            Executor::LoadDepthError,
+            "Sevgi load nesting too deep (maximum #{MAX_LOAD_DEPTH} active sources): #{source.file}"
+          )
         end
 
         @active[source.identity] = source
@@ -132,11 +140,10 @@ module Sevgi
       def execute(source, receiver, &boot)
         active = enter(source)
         @recent = run(source, receiver, &boot)
-        # rubocop:disable Lint/RescueException
+        # rubocop:disable-next Lint/RescueException
       rescue Exception => e
         @error = e
         throw(:result, self)
-        # rubocop:enable Lint/RescueException
       ensure
         leave(active)
       end

data/lib/sevgi/executor.rb

@@ -14,15 +14,15 @@ module Sevgi
   # useful load stack while keeping DSL methods out of the caller's global object
   # whenever possible. Active scope stacks are isolated per Ruby fiber, so
   # concurrent executions can perform nested `Load` calls without sharing scope
-  # state. The process SIGINT handler is shared by Ruby, so executor runs guard it
-  # with a reference-counted critical section and restore the previous handler
-  # after the last active execution finishes.
+  # state. The host owns process signal handlers. Execution captures an Interrupt
+  # only when Ruby delivers it inside the executing scope; worker executions do
+  # not take ownership of the main thread's signal policy.
   #
   # Consumers execute the full DSL through {Sevgi.execute} or {Sevgi.execute_file}, then inspect {Executor::Result},
-  # {Executor::Error}, and {Executor::CycleError}. The custom receiver and boot lifecycle is internal plumbing for the
-  # top-level API and Rake integration.
+  # {Executor::Error}, {Executor::CycleError}, and {Executor::LoadDepthError}. The custom receiver and boot lifecycle is
+  # internal plumbing for the top-level API and Rake integration.
   #
-  # @see https://sevgi.roktas.dev/execution/ Execution guide
+  # @see https://sevgi.roktas.dev/usage/#execute Execute source guide
   class Executor
     private_class_method :new
     private_constant :Scope
@@ -33,30 +33,12 @@ module Sevgi
     SOURCE_LINE_MAX = (2 ** 31) - 1
     private_constant :SCOPE_KEY, :SOURCE_LINE_MAX, :Source
 
-    # Owns mutable execution and process-signal state outside the public executor surface.
+    # Owns mutable execution state outside the public executor surface.
     # @api private
     class State
-      def initialize
-        @signal_count = 0
-        @signal_mutex = Mutex.new
-        @signal_previous = nil
-      end
-
       def create(scope = nil) = Scope.new(scope).tap { scopes << it }
       def current = scopes.last
 
-      def restore
-        @signal_mutex.synchronize do
-          next if @signal_count.zero?
-
-          @signal_count -= 1
-          next unless @signal_count.zero?
-
-          Signal.trap("INT", @signal_previous)
-          @signal_previous = nil
-        end
-      end
-
       def shutdown(scope = nil)
         return scopes.pop unless scope
         return scopes.pop if scopes.last.equal?(scope)
@@ -64,13 +46,6 @@ module Sevgi
         scopes.delete(scope)
       end
 
-      def trap
-        @signal_mutex.synchronize do
-          @signal_previous = Signal.trap("INT") { Kernel.abort("") } if @signal_count.zero?
-          @signal_count += 1
-        end
-      end
-
       private
 
       def scopes = Thread.current[SCOPE_KEY] ||= []
@@ -86,7 +61,7 @@ module Sevgi
     # @note Uses the active executor scope from the current fiber.
     # @api private
     def self.load(file, ...)
-      PanicError.("box stack empty; create a box first") unless STATE.current
+      PanicError.("No active executor scope") unless STATE.current
 
       STATE.current.load(file, ...)
     end
@@ -98,18 +73,17 @@ module Sevgi
     # @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 receiver [Object, nil] receiver used verbatim while booting the DSL; nil selects the isolated execution
+    # @param receiver [Object, nil] receiver used verbatim while booting the DSL. Nil selects the isolated execution
     #   module, while false and other executable objects remain explicit receivers
     # @yield optional boot block that installs DSL methods before evaluation
     # @yieldreturn [void]
     # @return [Sevgi::Executor::Result] immutable execution result
     # @raise [Sevgi::ArgumentError] when source, file, line, required library, or receiver is invalid
-    # @note Script and required-library failures are captured in {Sevgi::Executor::Result#error}; inspect
+    # @note Script and required-library failures are captured in {Sevgi::Executor::Result#error}. Inspect
     #   {Sevgi::Executor::Error#cause} for the original exception.
     # @note Empty source without `require:` is a strict no-op: no scope is created, the receiver and boot block are
     #   unused, and the result stack is empty. Supplying `require:` uses the normal boot and evaluation lifecycle.
-    # @note Reentrant and concurrent calls keep independent scope stacks per fiber. The temporary SIGINT handler remains
-    #   process-global while any execution is active.
+    # @note Reentrant and concurrent calls keep independent scope stacks per fiber and preserve the host's signal policy.
     # @api private
     def self.execute(string, file: nil, line: nil, require: nil, receiver: nil, &block)
       validate_source!(string, file, line)
@@ -122,18 +96,17 @@ module Sevgi
     # @param file [String] source file to read and execute
     # @param as [String, nil] logical source name used for evaluation and diagnostics
     # @param require [String, nil] optional Ruby library to require before execution
-    # @param receiver [Object, nil] receiver used verbatim while booting the DSL; nil selects the isolated execution
+    # @param receiver [Object, nil] receiver used verbatim while booting the DSL. Nil selects the isolated execution
     #   module, while false and other executable objects remain explicit receivers
     # @yield optional boot block that installs DSL methods before evaluation
     # @yieldreturn [void]
     # @return [Sevgi::Executor::Result] immutable execution result
     # @raise [Sevgi::ArgumentError] when file, logical source name, required library, or receiver is invalid
-    # @note File-read, script, and required-library failures are captured in {Sevgi::Executor::Result#error}; inspect
+    # @note File-read, script, and required-library failures are captured in {Sevgi::Executor::Result#error}. Inspect
     #   {Sevgi::Executor::Result#stack} for nested loads.
     # @note An empty file without `require:` is a strict no-op: no scope is created, the receiver and boot block are
     #   unused, and the result stack is empty. Supplying `require:` uses the normal boot and evaluation lifecycle.
-    # @note Reentrant and concurrent calls keep independent scope stacks per fiber. The temporary SIGINT handler remains
-    #   process-global while any execution is active.
+    # @note Reentrant and concurrent calls keep independent scope stacks per fiber and preserve the host's signal policy.
     # @api private
     def self.execute_file(file, as: nil, require: nil, receiver: nil, &block)
       ArgumentError.("Executor file must be a String") unless file.is_a?(::String)
@@ -156,32 +129,29 @@ module Sevgi
       private
 
       def capture_error(source, error)
-        acquired = STATE.trap
         scope = STATE.create
         scope.capture(source, error).result
       ensure
-        STATE.restore if acquired
         STATE.shutdown(scope) if scope
       end
 
       def execute_source(source, require:, receiver:, &block)
-        acquired = false
         return Result.new(value: nil, error: nil, stack: []) if source.string.empty? && require.nil?
 
-        acquired = STATE.trap
         scope = STATE.create
         catch(:result) { run_source(scope, source, require, receiver, &block) }
         scope.result
 
       ensure
-        STATE.restore if acquired
         STATE.shutdown(scope) if scope
       end
 
       def run_source(scope, source, library, receiver, &block)
         ::Kernel.require(library) if library
         scope.call(source, receiver, &block)
-      rescue ::LoadError => e
+        # Required libraries use the same failure policy as executable script source.
+        # rubocop:disable-next Lint/RescueException
+      rescue ::Exception => e
         scope.capture(source, e)
       end
 

data/lib/sevgi/skill.rb

@@ -14,7 +14,7 @@ module Sevgi
     def path
       spec = ::Gem::Specification.find_by_name("sevgi-appendix", "= #{::Sevgi::VERSION}")
       packaged = packaged_path(spec)
-      # Package managers may replace a versioned gem path with their stable prefix.
+      # Package managers can replace a versioned gem path with their stable prefix.
       path = ::File.expand_path(ENV.fetch("SEVGI_SKILL", packaged))
 
       Error.("Sevgi skill is unavailable at #{path}.") unless ::File.file?(::File.join(path, "SKILL.md"))

data/lib/sevgi/svg.rb

@@ -3,11 +3,12 @@
 module Sevgi
   # Public SVG facade installed by `require "sevgi"`.
   #
-  # Capitalized methods are SVG DSL operations: {SVG.Canvas} creates a canvas,
-  # {SVG.Document} defines a document profile, and {SVG.Paper} registers a
-  # paper size. Double-colon names are Ruby constants and types, such as
-  # {SVG::Canvas} and {SVG::Document}. The global `SVG(...)` method builds a
-  # drawing; there is intentionally no stuttering `SVG.SVG(...)` form.
+  # Capitalized methods are SVG DSL operations and constructors: {SVG.Canvas}
+  # creates a canvas, {SVG.Document} defines a document profile, {SVG.Module}
+  # builds a callable drawing module, and {SVG.Paper} registers a paper size.
+  # Double-colon names are Ruby constants and types, such as {SVG::Canvas},
+  # {SVG::Document}, and {SVG::Module}. The global `SVG(...)` method builds a
+  # drawing. There is intentionally no stuttering `SVG.SVG(...)` form.
   #
   # Lowercase constructors remain on {Sevgi::Graphics} for focused component
   # use. Script execution belongs to {Sevgi.execute} and is not part of this
@@ -26,8 +27,9 @@ module Sevgi
   # @example Distinguish an operation from its result type
   #   canvas = SVG.Canvas width: 24, height: 24, unit: :px
   #   canvas.is_a?(SVG::Canvas) #=> true
-  # @see https://sevgi.roktas.dev/getting-started/ Getting started
-  # @see https://sevgi.roktas.dev/library-mode/ Library mode guide
+  # @see https://sevgi.roktas.dev/start/ Getting started
+  # @see https://sevgi.roktas.dev/usage/ Usage guide
+  # @see https://sevgi.roktas.dev/compose/ Composition guide
   module SVG
     # SVG attribute collection and normalization API.
     Attributes = Graphics::Attributes
@@ -114,6 +116,11 @@ module Sevgi
     # @see Sevgi::Toplevel#Grid
     def self.Grid(...) = Sevgi.Grid(...)
 
+    # Fits major and minor intervals into a span.
+    # @return [Sevgi::Sundries::Ruler] fitted ruler
+    # @see Sevgi::Toplevel#Ruler
+    def self.Ruler(...) = Sevgi.Ruler(...)
+
     # Loads nested `.sevgi` files through the active executor scope.
     # @return [Array<String>] requested file names
     # @see Sevgi::Toplevel#Load
@@ -124,6 +131,28 @@ module Sevgi
     # @see Sevgi::Toplevel#Mixin
     def self.Mixin(...) = Sevgi.Mixin(...)
 
+    # Builds an anonymous callable drawing module.
+    # The callable contract is installed before the optional definition runs, so `base` and drawing-method tracking
+    # are available throughout the block. The definition keeps its ordinary Ruby lexical constant scope.
+    # @yield [mod] optionally defines the callable module
+    # @yieldparam mod [Module] module being defined
+    # @yieldreturn [Object] ignored definition result
+    # @return [Module] new anonymous module extended with {SVG::Module}
+    # @example Build a callable drawing module
+    #   label = SVG.Module do
+    #     base { circle r: 8, fill: "seagreen" }
+    #     def call(value) = text value
+    #   end
+    #
+    #   SVG(:minimal) { Call label, "OK" }
+    # @see SVG::Module
+    def self.Module(&definition)
+      mod = ::Module.new
+      mod.extend(Graphics::Module)
+      mod.module_eval(&definition) if definition
+      mod
+    end
+
     # Defines or validates a named paper profile.
     # @return [Symbol, String] original paper profile name
     # @see Sevgi::Toplevel#Paper

data/lib/sevgi/toplevel/derender.rb

@@ -27,7 +27,8 @@ module Sevgi
     # @see Sevgi::Derender.decompile_file
     def DecompileFile(file, id: nil, omit: nil) = Derender.decompile_file(file, id:, omit:)
 
-    # Converts inline SVG/XML content into Sevgi DSL Ruby source.
+    # Converts inline SVG/XML content into Sevgi DSL Ruby source. The returned String is ordinary Ruby source. Review
+    # and integrate it statically rather than using Ruby's raw dynamic evaluation methods.
     # @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
@@ -39,7 +40,8 @@ module Sevgi
     # @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.
+    # Converts an SVG/XML file into Sevgi DSL Ruby source. The returned String is ordinary Ruby source. Review and
+    # integrate it statically rather than using Ruby's raw dynamic evaluation methods.
     # @param file [String] path to the source SVG/XML file
     # @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

data/lib/sevgi/toplevel/executor.rb

@@ -22,16 +22,17 @@ module Sevgi
   # @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 https://sevgi.roktas.dev/execution/ Execution guide
+  # @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. The host retains its signal
+  #   handlers. An Interrupt is captured only if it reaches this execution, not redirected from the main thread.
+  # @see https://sevgi.roktas.dev/usage/#execute Execute source 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 file [String] source file to read and execute
-  # @param as [String, nil] source basename used for evaluation, diagnostics, and caller-derived output defaults;
+  # @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
@@ -40,9 +41,10 @@ module Sevgi
   # @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 https://sevgi.roktas.dev/execution/ Execution guide
+  # @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. The host retains its signal
+  #   handlers. An Interrupt is captured only if it reaches this execution, not redirected from the main thread.
+  # @see https://sevgi.roktas.dev/usage/#execute Execute source 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)
@@ -71,7 +73,7 @@ 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.
+    # @note Ordinary library code uses Ruby `require`. `Load` is available only during Sevgi script execution.
     # @see Sevgi.Load
     # @see Sevgi.execute_file
     def Load(*files)

data/lib/sevgi/toplevel/graphics.rb

@@ -64,7 +64,8 @@ module Sevgi
     end
 
     # Builds an SVG document through the full Sevgi top-level DSL.
-    # @param document [Symbol, String, Class] document profile name or document class
+    # @param document [Symbol, String, Class, Sevgi::Graphics::Canvas, Sevgi::Graphics::Paper] document profile,
+    #   document class, or canvas input that uses the default profile
     # @param canvas [Sevgi::Graphics::Canvas, Sevgi::Graphics::Paper, Symbol, String, Sevgi::Undefined, nil] optional
     #   canvas or paper profile
     # @param attributes [Hash] root SVG attributes

data/lib/sevgi/toplevel/sundries.rb

@@ -4,12 +4,23 @@ require "sevgi/sundries"
 
 module Sevgi
   module Toplevel
+    # Fits major and minor intervals into a span without drawing SVG elements.
+    # @overload Ruler(brut:, unit:, multiple:, margins: [0.0])
+    #   @param brut [Numeric] full available span
+    #   @param unit [Numeric] minor interval length
+    #   @param multiple [Integer] minor intervals per major interval
+    #   @param margins [Array<Numeric>] one symmetric or two start/end minimum margins
+    #   @return [Sevgi::Sundries::Ruler] fitted ruler
+    #   @raise [Sevgi::ArgumentError] when the span, intervals, or margins are invalid
+    # @see Sevgi::Sundries::Ruler#initialize
+    def Ruler(...) = Sundries::Ruler.new(...)
+
     # 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.
+    # `(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

data/lib/sevgi/toplevel.rb

@@ -3,12 +3,11 @@
 module Sevgi
   # Shared implementation for the full Sevgi top-level DSL.
   #
-  # This module is installed by `include Sevgi` or `extend Sevgi`; it should not
+  # This module is installed by `include Sevgi` or `extend Sevgi`. Consumers do not
   # 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
+  # @see https://sevgi.roktas.dev/usage/ Usage guide
   module Toplevel
     @promotions = {}
 

data/lib/sevgi/version.rb

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

data/lib/sevgi.rb

@@ -18,13 +18,14 @@ 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, String, Class] document profile name or document class
+#   @param document [Symbol, String, Class, Sevgi::Graphics::Canvas, Sevgi::Graphics::Paper] document profile,
+#     document class, or canvas input that uses the default profile
 #   @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
+#   @return [Sevgi::Graphics::Document::Proto] an SVG document object, ready for separate rendering
 #   @raise [Sevgi::ArgumentError] when the document, paper, or canvas arguments are invalid
 # @example Build through the global library entrypoint
 #   SVG(:minimal) { circle r: 4 }.Render
@@ -35,26 +36,25 @@ def SVG(...) = Sevgi.SVG(...)
 # Full top-level API for Sevgi library and script consumers.
 #
 # `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.
+# 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`. Promoted toolkit operations are also
+# available on `Sevgi` for consumers that prefer the full namespace. {SVG.Module} is a facade-only convenience
+# constructor. Process-level operations such as {Sevgi.execute} remain on `Sevgi`, not 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
+# `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`.
+# 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
+# @see https://sevgi.roktas.dev/usage/ Usage guide
+# @see https://sevgi.roktas.dev/compose/ Composition guide
 module Sevgi
   # @!method self.Canvas(...)
   #   Builds a canvas from a paper profile or explicit dimensions.
@@ -88,6 +88,10 @@ module Sevgi
   #   Fits a drawable grid to a graphics canvas.
   #   @return [Sevgi::Sundries::Grid] fitted grid
   #   @see Sevgi::Toplevel#Grid
+  # @!method self.Ruler(...)
+  #   Fits major and minor intervals into a span.
+  #   @return [Sevgi::Sundries::Ruler] fitted ruler
+  #   @see Sevgi::Toplevel#Ruler
   # @!method self.Decompile(...)
   #   Converts inline SVG/XML into an immutable Derender node.
   #   @return [Sevgi::Derender::Node] selected node

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sevgi
 version: !ruby/object:Gem::Version
-  version: 0.98.2
+  version: 1.0.0
 platform: ruby
 authors:
 - Recai Oktaş
@@ -15,98 +15,98 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.98.2
+        version: 1.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.98.2
+        version: 1.0.0
 - !ruby/object:Gem::Dependency
   name: sevgi-derender
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.98.2
+        version: 1.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.98.2
+        version: 1.0.0
 - !ruby/object:Gem::Dependency
   name: sevgi-function
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.98.2
+        version: 1.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.98.2
+        version: 1.0.0
 - !ruby/object:Gem::Dependency
   name: sevgi-geometry
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.98.2
+        version: 1.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.98.2
+        version: 1.0.0
 - !ruby/object:Gem::Dependency
   name: sevgi-graphics
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.98.2
+        version: 1.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.98.2
+        version: 1.0.0
 - !ruby/object:Gem::Dependency
   name: sevgi-standard
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.98.2
+        version: 1.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.98.2
+        version: 1.0.0
 - !ruby/object:Gem::Dependency
   name: sevgi-sundries
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.98.2
+        version: 1.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.98.2
+        version: 1.0.0
 description: Loads the complete Sevgi API and runs .sevgi scripts.
 email: roktas@gmail.com
 executables:
@@ -161,7 +161,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 4.0.20
 specification_version: 4
 summary: Ruby toolkit for creating SVG.
 test_files: []