sevgi-sundries 0.95.0 → 0.98.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3dec50633b4f3c460af91dc1ab19341355f3ede4dd1df4bac99d4ab076b0ac53
-  data.tar.gz: b6d478d2d796f1a6379f1a40301795b41f9dca9ad68cce017e17b2c369703641
+  metadata.gz: 7df3ccce8a77f50c584bd9ced3fec7fa19c3efb7c458d8dc248ca3629666fca3
+  data.tar.gz: 690408c4e42c34eb5fe500d405a6f2532c9b7f1b6350784d176ba77f40135ea8
 SHA512:
-  metadata.gz: 9f36b8b5f8d7ca21602e67a50cc3272d452c4308a57b4773c94232337de9b236505e4283f09ffb85f57827087975b8ba53be8ee9d72b41b8f2d111ab6ec5ada3
-  data.tar.gz: f82107592d7771d7ce72cbfc16276db3994097385a10205748064515110faba49b5c3fef842c405deb8b6f4746940736cb985f79be750ed9c58fdb674a014a7b
+  metadata.gz: c2c0a0062705f0c9dd55a0cef7093965a14cb9ce5e9f55ad9ca5f72485f715220fd8e9fdd616e707bf21eb3b198cb5011068aee9fff351c4e55e1aea5b03264a
+  data.tar.gz: 72ef749c915cc8782e313292a5da66960f5c50dce49cc071fa2492de97d2d948f3f28f05475290daf979e29247f9ae61a63e347077ceb1a923ec16746e7ddaad

data/CHANGELOG.md

@@ -5,6 +5,131 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## Unreleased
 
+## 0.98.2 - 2026-07-25
+
+### Fixed
+
+- Restored the `sevgi` CLI's main-object scope so bare toolkit calls remain available inside script helper classes.
+
+## 0.98.1 - 2026-07-20
+
+### Changed
+
+- Changed the `sevgi` CLI to use the executor's isolated scope by default.
+
+### Removed
+
+- Removed the redundant `-n` and `--nomain` CLI options; library consumers can still select `main: true` through
+  `Sevgi.execute` and `Sevgi.execute_file` when needed.
+
+## 0.98.0 - 2026-07-20
+
+### Added
+
+- Added standard-input support to `sevgi`, `igves`, and `igsev`; `sevgi --as NAME` and
+  `Sevgi.execute_file(..., as: NAME)` supply the logical source basename used by implicit SVG, PDF, and PNG
+  destinations without changing physical load identity.
+
+## 0.97.0 - 2026-07-19
+
+### Added
+
+- Added `sevgi-appendix`, containing the Sevgi agent skill and a RuboCop plugin for preserving readable `.sevgi` DSL
+  source alongside rubyfmt-formatted Ruby; the umbrella `sevgi` gem installs the matching Appendix version.
+- Added `sevgi --skill` to report the validated path of the matching packaged agent skill for product-neutral setup.
+- Added `igsev` to the umbrella gem for normalizing an SVG file through a complete SVG-to-Sevgi-to-SVG round trip.
+
+### Changed
+
+- Made Homebrew the recommended complete CLI installation while retaining Bundler and focused component gems for Ruby
+  application dependencies.
+
+## 0.96.0 - 2026-07-18
+
+### Added
+
+- Added exact, subtree-wide attribute omission to Derender content/file conversion, evaluation, and inclusion APIs;
+  `igves --omit` exposes the same behavior from the command line.
+- Added `Sevgi.SVG` as the explicit namespaced form of the top-level SVG document entrypoint.
+- Added the opt-in recursive `SVG::Modules` contract for callable drawing namespaces.
+- Added callable drawing-module `base` blocks, document and paper registry introspection, Canvas structural equality,
+  renderer options on `RenderChildren`, axis translation helpers, and a CC BY RDF helper.
+- Formalized non-rendering `-` metadata and `+` attribute updates as `Attributes::META_PREFIX` and
+  `Attributes::UPDATE_SUFFIX`; repeated Array updates now concatenate into a stable flat value.
+
+### Changed
+
+- Breaking: replaced the `SVG = Sevgi::Graphics` alias with an independent SVG facade. Facade operations now use
+  capitalized names such as `SVG.Canvas` and `SVG.Document`; lowercase component helpers remain on
+  `Sevgi::Graphics`, and the stuttering `SVG.SVG` form was removed.
+- Breaking: made low-level `Executor.execute` and `execute_file` runners private; consumers use
+  `Sevgi.execute` and `Sevgi.execute_file` while retaining the public result and error types.
+- Breaking: removed the abstract `Document::Base` layer from the selectable document-profile registry; `Minimal` and
+  `Default` are now sibling concrete profiles, and custom profile hierarchies should derive from `Base`.
+- Breaking: renamed Parallelogram segment and constraint arguments by geometric role: `base`, `side`, and
+  `constraint` replace axis-implying constructor names.
+- Made degree-based sine and cosine exact at integer quarter turns, eliminating cardinal Geometry residue.
+- Documented complete file-system failure families for file comparison, output, touch, and upward location helpers.
+- Formalized generated Tile ids, positional CSS classes, template placement, and per-use callback signatures.
+- Formalized String and Symbol ids across Derender selection APIs and documented file-read failures consistently.
+- Breaking: made top-level `Decompile`, `Derender`, `Evaluate`, and `EvaluateChildren` consume inline SVG/XML;
+  file inputs now use the corresponding `File`-suffixed entrypoints.
+- Breaking: replaced callable drawing module `call` block registration with argument-independent `base` blocks;
+  inherited bases run parent-first, and modules with one drawing method conventionally name it `call`.
+- Breaking: made bracket and call notation the canonical Geometry constructors. Among Data value types, bracket notation
+  is public only for Point, Segment, LengthAngle, Margin, and Paper; use `.new` for Location and result carriers, and
+  `Stay` for traversal stop tokens.
+- Breaking: aligned Point and Segment comparison with Ruby `Comparable`; malformed or unrelated comparison operands now
+  return nil from `<=>`.
+- Breaking: executor entrypoints now return immutable `Executor::Result` values and expose only `execute` and
+  `execute_file`; inspect `result.error`, `result.stack`, and `result.value` instead of executor scopes or lifecycle state.
+- Breaking: wrapper attributes and callable arguments use distinct channels, `With` rejects parentless receivers, and
+  unsupported direct constructors are private; use the documented factories for Content, concrete Geometry lined
+  elements, and Grid query values.
+- Breaking: Canvas uses `.new` for explicit fields, `.from_paper(paper, **overrides)` for paper conversion, and
+  `.call`/`Graphics.canvas` for dispatch; the misleading keyword-only `.from_paper(width:, height:)` form was removed.
+- Breaking: `Save`, `Write`, `PNG`, `PDF`, and Sundries native export normalize successful destinations to expanded
+  String paths and create missing parent directories; change-aware SVG writes still return nil when unchanged.
+- Breaking: renamed `Derender.evaluate_file_children` to `evaluate_children_file`; decompiled nodes now own immutable
+  public state while parser, strategy, and construction plumbing remain private.
+- Expanded runtime/YARD parity checks and exact contracts for inherited, extended, generated, and dynamic API surfaces,
+  forwarded options, error channels, path ownership, whitespace, namespaces, nil behavior, and return values.
+
+### Fixed
+
+- Rejected directories from default file discovery while preserving custom locator matchers.
+- Kept `Ancestral` context in non-rendering `-context` metadata instead of leaking it into SVG attributes.
+- Preserved source Canvas units and names when deriving fitted Grid canvases.
+- Prevented stale documentation assets from mixing old layouts with new HTML, and moved sidebar navigation into the
+  tablet menu at 1024px and below.
+- Normalized numeric slots owned by path, shape, transform, tile, and Inkscape page helpers to finite SVG number spelling;
+  arbitrary user-supplied attributes remain untouched.
+- Made named callable wrapper and symbol ids stable while omitting defaults for anonymous modules, and indexed every
+  rendered id value, including false and numeric values, through its serialized string.
+- Preserved signed Geometry constraint directions, rejected invalid sweep/export channels through Sevgi error families,
+  and validated raw output paths before expansion or rendering.
+- Made callable module configuration copy-owned and freeze-aware, document subclasses inherit their nearest profile, and
+  false executor boot receivers remain explicit rather than defaulting to an internal scope.
+- Made element trees, attributes, identifiers, locator results, document profiles, Derender nodes, shell results, and
+  executor results retain owned immutable snapshots where their public contracts promise value semantics.
+- Corrected Shell combined-output separators, nil export density errors, document render-option routing, executor source
+  snapshots, selected-node namespace/whitespace documentation, and Standard character-data validation.
+
+### Removed
+
+- Removed public access to pluralization tables and the internal SVG save extension; pluralization rules are now deeply
+  immutable.
+- Removed public documentation and constant access for command-line implementation modules; the `sevgi` and `igves`
+  executables remain unchanged.
+- Removed eager loading and public documentation of private Showcase build/test support; explicit support entrypoints
+  now keep the harness under the Showcase namespace.
+- Removed public access to document profile name normalizers; registry operations retain them as private plumbing.
+- Removed the redundant `Margin.margin` constructor; use canonical bracket notation.
+- Removed public executor orchestration, obsolete callable-module hooks, the old public attribute syntax constants, and
+  direct construction of abstract or internally wired Content, Element, and Grid query types.
+- Removed accidental public access to abstract Lined factories, internal element-name/export maps, result/location
+  bracket constructors, and direct Stop construction.
+
 ## 0.95.0 - 2026-07-11
 
 ### Security

data/README.md

@@ -1,6 +1,6 @@
 # Sevgi Sundries
 
-Helper objects and export tools for Sevgi drawings.
+Sevgi Sundries contains shared layout objects and optional export tools.
 
 ## Install
 
@@ -24,7 +24,7 @@ tile.box.height
 
 ## Ruby compatibility
 
-Requires Ruby 3.4.0 or newer. CI verifies Ruby 3.4.0 and the current development Ruby from `.ruby-version`.
+Requires Ruby 3.4.0 or newer. CI verifies the current Ruby 3.4 release and the development Ruby from `.ruby-version`.
 
 ## Native prerequisites
 
@@ -49,7 +49,7 @@ gem install cairo rsvg2 hexapdf
 
 ## Links
 
-- Documentation: https://sevgi.roktas.dev
-- API documentation: https://www.rubydoc.info/gems/sevgi-sundries
-- Source: https://github.com/roktas/sevgi/tree/main/sundries
-- Changelog: https://github.com/roktas/sevgi/blob/main/CHANGELOG.md
+- Documentation: <https://sevgi.roktas.dev>
+- API documentation: <https://www.rubydoc.info/gems/sevgi-sundries>
+- Source: <https://github.com/roktas/sevgi/tree/main/sundries>
+- Changelog: <https://github.com/roktas/sevgi/blob/main/CHANGELOG.md>

data/lib/sevgi/sundries/export/native.rb

@@ -20,29 +20,32 @@ module Sevgi
 
       # Exports SVG source to a PDF or PNG file using librsvg and Cairo.
       # @param svg [String] SVG source content
-      # @param output [String, #to_s] output file path
+      # Relative paths are expanded, missing parent directories are created after all render inputs validate, and an
+      # existing output file is replaced. Directory paths are not expanded to a default file name.
+      # @param output [String, #to_path] output file path
       # @param format [Symbol, String, nil] explicit output format, or nil to infer from output extension
       # @param width [Numeric, nil] finite positive target width in output pixels for PNG, or CSS pixels before PDF point conversion
       # @param height [Numeric, nil] finite positive target height in output pixels for PNG, or CSS pixels before PDF point conversion
-      # @param dpi [Numeric] finite positive CSS pixel density used for absolute SVG units and PDF point conversion
+      # @param dpi [Numeric] finite positive CSS pixel density; omission uses {DEFAULT_DPI}, but explicit nil is invalid
       # @param css [String, nil] CSS inserted before the closing svg tag before rendering
       # @yield [svg] optional source transformation applied before rendering
       # @yieldparam svg [String] SVG source after optional CSS injection
       # @yieldreturn [String] SVG source to render
-      # @return [Object] the original output argument
-      # @raise [Sevgi::ArgumentError] when output, CSS, or transformed SVG has an invalid type
-      # @raise [Sevgi::Sundries::Export::ExportError] when format, numeric options, SVG parsing, SVG dimensions, or render dimensions are invalid
+      # @return [String] expanded output path
+      # @raise [Sevgi::ArgumentError] when output is blank, invalid, or a directory, or CSS/transformed SVG has an
+      #   invalid type
+      # @raise [Sevgi::Sundries::Export::ExportError] when format, numeric options, CSS insertion, SVG parsing, SVG dimensions, or render dimensions are invalid
+      # @raise [SystemCallError] when the output directory or file cannot be created or written
       def call(svg, output, format: nil, width: nil, height: nil, dpi: DEFAULT_DPI, css: nil, &block)
         ArgumentError.("SVG content must be a String") unless svg.is_a?(String)
-        original_output = output
         output = output_path(output)
-        format = format_for!(format, output)
+        format = format_for(format, output)
         width = dimension(width, "width")
         height = dimension(height, "height")
-        dpi = dimension(dpi, "dpi")
+        dpi = dimension(dpi, "dpi", optional: false)
         ArgumentError.("Export CSS must be a String") unless css.nil? || css.is_a?(String)
 
-        svg = inject(svg, css) if css && !css.strip.empty?
+        svg = styled(svg, css) if css && !css.strip.empty?
         svg = block.call(svg) if block
         ArgumentError.("SVG content must be a String") unless svg.is_a?(String)
 
@@ -62,6 +65,7 @@ module Sevgi
           tw, th = target_size(iw, ih, width, height)
           ExportError.("Invalid export dimensions") unless target_size?(format, tw, th)
 
+          ::FileUtils.mkdir_p(::File.dirname(output))
           renderer.call(
             handle: handle,
             output: output,
@@ -75,7 +79,7 @@ module Sevgi
           ExportError.("Render error: #{e.message}")
         end
 
-        original_output
+        output
       end
 
       # Replaces exact placeholder text objects in PDF streams.
@@ -308,19 +312,21 @@ module Sevgi
         def output_path(output)
           ArgumentError.("Export output must be provided") if output.nil?
 
-          path = output.to_s
-          ArgumentError.("Export output must be a String-like path") unless path.is_a?(::String)
+          path = output.respond_to?(:to_path) ? output.to_path : output
+          ArgumentError.("Export output must be a String or path-like object") unless path.is_a?(::String)
           ArgumentError.("Export output must be provided") if path.strip.empty?
 
+          path = ::File.expand_path(path)
+          ArgumentError.("Export output must name a file") if ::File.directory?(path)
           path
         rescue ::StandardError => e
           raise if e.is_a?(::Sevgi::ArgumentError)
 
-          ArgumentError.("Export output must be a String-like path: #{e.message}")
+          ArgumentError.("Export output must be a String or path-like object: #{e.message}")
         end
 
-        def dimension(value, field)
-          return if value.nil?
+        def dimension(value, field, optional: true)
+          return if value.nil? && optional
           ExportError.(dimension_error(field)) unless value.is_a?(::Numeric)
 
           number = begin

data/lib/sevgi/sundries/export/system.rb

@@ -40,7 +40,7 @@ module Sevgi
       # @param page [Integer, String, nil] page selector passed to Inkscape
       # @param css [String, nil] CSS inserted before exporting
       # @return [Sevgi::Function::Shell::Result] command result
-      # @raise [Sevgi::Sundries::Export::ExportError] when format or output extension is unsupported
+      # @raise [Sevgi::Sundries::Export::ExportError] when format, output extension, or CSS insertion is invalid
       # @raise [Sevgi::Error] when Inkscape is missing or the command fails
       # @raise [Errno::ENOENT] when the executable cannot be spawned
       # @see https://inkscape.org/ Inkscape
@@ -59,11 +59,11 @@ module Sevgi
         infile = File.expand_path(infile)
         outfile ||= F.subext(".pdf", infile)
         outfile = File.expand_path(outfile)
-        format = format_for!(format, outfile)
+        format = format_for(format, outfile)
 
         if css
           temp = Tempfile.new(%w[input .svg], File.dirname(infile))
-          ::File.write(temp.path, inject(::File.read(infile), css))
+          ::File.write(temp.path, styled(::File.read(infile), css))
           infile = temp.path
         end
 
@@ -98,7 +98,7 @@ module Sevgi
       # @param id [String, nil] SVG element id to export
       # @param css [String, nil] CSS inserted before exporting
       # @return [Sevgi::Function::Shell::Result] command result
-      # @raise [Sevgi::Sundries::Export::ExportError] when format or output extension is unsupported
+      # @raise [Sevgi::Sundries::Export::ExportError] when format, output extension, or CSS insertion is invalid
       # @raise [Sevgi::Error] when rsvg-convert is missing or the command fails
       # @raise [Errno::ENOENT] when the executable cannot be spawned
       # @see https://gitlab.gnome.org/GNOME/librsvg librsvg
@@ -115,11 +115,11 @@ module Sevgi
         infile = File.expand_path(infile)
         outfile ||= F.subext(".pdf", infile)
         outfile = File.expand_path(outfile)
-        format = format_for!(format, outfile)
+        format = format_for(format, outfile)
 
         if css
           temp = Tempfile.new(%w[input .svg], File.dirname(infile))
-          ::File.write(temp.path, inject(::File.read(infile), css))
+          ::File.write(temp.path, styled(::File.read(infile), css))
           infile = temp.path
         end
 

data/lib/sevgi/sundries/export.rb

@@ -6,19 +6,32 @@ require_relative "export/system"
 
 module Sevgi
   module Sundries
-    # Exports SVG content and post-processes PDF output.
+    # Exports SVG source to PNG or PDF and post-processes PDF output.
     #
     # Native PDF/PNG rendering is loaded lazily so installing `sevgi-sundries` for SVG-only helpers does not require the
     # Cairo, RSVG, or HexaPDF gems. Native export entrypoints raise {Sevgi::MissingComponentError} when those optional
-    # gems are unavailable.
+    # gems are unavailable. Omit `format:` to infer it from the output suffix;
+    # width and height are output dimensions rather than changes to the SVG
+    # viewBox. The return value is the expanded path that was written.
+    #
+    # @example Export SVG source to a sized PNG
+    #   svg = Sevgi::Graphics.SVG(:minimal) { circle cx: 5, cy: 5, r: 4 }.Render
+    #   Sevgi::Sundries::Export.call(svg, "drawing.png", width: 320)
+    # @example Infer PDF output and inject export-only CSS
+    #   svg = Sevgi::Graphics.SVG(:minimal) { circle class: "accent", r: 4 }.Render
+    #   Sevgi::Sundries::Export.call(svg, "drawing.pdf", css: ".accent { fill: tomato; }")
+    # @see https://sevgi.roktas.dev/sundries/#export Export guide
     module Export
-      # Supported export format names mapped to file extensions.
-      AVAILABLE = (EXTENSIONS = {
+      # File extensions mapped to export format names.
+      # @api private
+      EXTENSIONS = {
         ".pdf" => :pdf,
         ".png" => :png
-      }.freeze)
-        .invert
-        .freeze
+      }.freeze
+      private_constant :EXTENSIONS
+
+      # Supported export format names mapped to file extensions.
+      AVAILABLE = EXTENSIONS.invert.freeze
 
       # Default SVG CSS pixel density.
       DEFAULT_DPI = 96.0
@@ -37,28 +50,26 @@ module Sevgi
       # @overload call(svg, output, format: nil, width: nil, height: nil, dpi: DEFAULT_DPI, css: nil)
       #   Exports SVG source to a PDF or PNG file using the optional native export gems.
       #   @param svg [String] SVG source content
-      #   @param output [String, #to_s] output file path
+      #   Relative paths are expanded, missing parent directories are created after all render inputs validate, and an
+      #   existing output file is replaced. Directory paths are not expanded to a default file name.
+      #   @param output [String, #to_path] output file path
       #   @param format [Symbol, String, nil] explicit output format, or nil to infer from output extension
       #   @param width [Numeric, nil] target width in output pixels for PNG, or CSS pixels before PDF point conversion
       #   @param height [Numeric, nil] target height in output pixels for PNG, or CSS pixels before PDF point conversion
-      #   @param dpi [Numeric] CSS pixel density used for absolute SVG units and PDF point conversion
+      #   @param dpi [Numeric] finite positive CSS pixel density; omission uses {DEFAULT_DPI}, but explicit nil is invalid
       #   @param css [String, nil] CSS inserted before the closing svg tag before rendering
       #   @yield [svg] optional source transformation applied before rendering
       #   @yieldparam svg [String] SVG source after optional CSS injection
       #   @yieldreturn [String] SVG source to render
-      #   @return [Object] the original output argument
-      #   @raise [Sevgi::ArgumentError] when SVG content is not a string or output is blank
+      #   @return [String] expanded output path
+      #   @raise [Sevgi::ArgumentError] when SVG content is not a string or output is blank, invalid, or a directory
       #   @raise [Sevgi::MissingComponentError] when cairo, hexapdf, or rsvg2 is unavailable
-      #   @raise [Sevgi::Sundries::Export::ExportError] when format, SVG parsing, SVG dimensions, or render dimensions
-      #     are invalid
+      #   @raise [Sevgi::Sundries::Export::ExportError] when format, CSS insertion, SVG parsing, SVG dimensions, or
+      #     render dimensions are invalid
+      #   @raise [SystemCallError] when the output directory or file cannot be created or written
       def call(*args, **kwargs, &block) = native!.call(*args, **kwargs, &block)
 
-      # Resolves the export format from an explicit value or output extension.
-      # @param format [Symbol, String, nil] explicit format
-      # @param output [String, #to_s] output path
-      # @return [Symbol] resolved format
-      # @raise [Sevgi::Sundries::Export::ExportError] when the explicit format or output extension is unsupported
-      def format_for!(format, output)
+      def format_for(format, output)
         if format
           format = normalize_format(format)
           ExportError.("Unsupported export format: #{format}") unless AVAILABLE.key?(format)
@@ -72,12 +83,12 @@ module Sevgi
         end
       end
 
-      # Inserts CSS before the closing svg tag.
-      # @param svg [String] SVG source content
-      # @param css [String] CSS source content
-      # @return [String] SVG source with an added style element when a closing svg tag is present
-      # @raise [NoMethodError] when SVG content does not support string substitution
-      def inject(svg, css) = svg.sub("</svg>", "<style>#{css}</style></svg>")
+      def styled(svg, css)
+        output = svg.sub("</svg>", "<style>#{css}</style></svg>")
+        ExportError.("Cannot insert CSS: closing svg tag not found") if output == svg
+
+        output
+      end
 
       def normalize_format(format)
         unless format.is_a?(::String) || format.is_a?(::Symbol)
@@ -87,7 +98,7 @@ module Sevgi
         format.to_sym
       end
 
-      private :normalize_format
+      private :format_for, :normalize_format, :styled
 
       # Replaces exact placeholder text objects in PDF streams.
       # @param infile [String] source PDF file path

data/lib/sevgi/sundries/grid.rb

@@ -5,6 +5,34 @@ require "delegate"
 module Sevgi
   module Sundries
     # Builds a tile-like grid from horizontal and vertical rulers.
+    #
+    # Axis names describe line direction, not the coordinate used to place a
+    # line: `grid.x` produces horizontal lines whose y positions come from the
+    # vertical ruler; `grid.y` produces vertical lines whose x positions come
+    # from the horizontal ruler. Each query can return geometry lines, Point
+    # endpoint pairs, or plain coordinate pairs for different consumers.
+    # @example Query fitted horizontal and vertical lines
+    #   x = Sevgi::Sundries::Ruler.new(brut: 80, unit: 1, multiple: 10, margins: [5])
+    #   y = Sevgi::Sundries::Ruler.new(brut: 50, unit: 1, multiple: 10, margins: [5])
+    #   grid = Sevgi::Sundries::Grid[x, y]
+    #   grid.x.major.lines.size # => 5
+    #   grid.y.minor.lines.size # => 71
+    # @example Preserve a source canvas while fitting axis margins
+    #   canvas = Sevgi::Graphics::Canvas.call(width: 80, height: 50)
+    #   x = Sevgi::Sundries::Ruler.new(brut: 80, unit: 1, multiple: 10, margins: [5, 7])
+    #   y = Sevgi::Sundries::Ruler.new(brut: 50, unit: 1, multiple: 10, margins: [3, 5])
+    #   grid = Sevgi::Sundries::Grid.new(x:, y:, canvas:)
+    #   grid.canvas.margin.to_a # => [4.0, 11.0, 6.0, 9.0]
+    # @example Use lines, points, coordinate pairs, and inherited row boxes
+    #   x = Sevgi::Sundries::Ruler.new(brut: 30, unit: 1, multiple: 10)
+    #   y = Sevgi::Sundries::Ruler.new(brut: 20, unit: 1, multiple: 10)
+    #   grid = Sevgi::Sundries::Grid[x, y]
+    #   grid.x.major.lines.size  # => 3
+    #   grid.x.major.points.first.map(&:deconstruct) # => [[0.0, 0.0], [30.0, 0.0]]
+    #   grid.y.halve.xys.first   # => [[5.0, 0.0], [5.0, 20.0]]
+    #   grid.rowbox.approx.height # => 10.0
+    # @see Sevgi::Sundries::Ruler
+    # @see Sevgi::Graphics::Mixtures::Hatch
     class Grid < Tile
       # Builds a grid using bracket syntax.
       # @param x [Sevgi::Sundries::Ruler] horizontal ruler
@@ -13,34 +41,55 @@ module Sevgi
       # @raise [Sevgi::ArgumentError] when either argument is not a ruler
       def self.[](x, y) = new(x:, y:)
 
-      # Returns the horizontal axis ruler and line queries.
+      # Returns the horizontal-line axis and its ruler queries.
+      # Line positions are supplied by the vertical ruler.
       # @return [Sevgi::Sundries::Grid::X]
       attr_reader :x
 
-      # Returns the vertical axis ruler and line queries.
+      # Returns the vertical-line axis and its ruler queries.
+      # Line positions are supplied by the horizontal ruler.
       # @return [Sevgi::Sundries::Grid::Y]
       attr_reader :y
 
       # Creates a grid from horizontal and vertical rulers.
       # @param x [Sevgi::Sundries::Ruler] horizontal ruler
       # @param y [Sevgi::Sundries::Ruler] vertical ruler
+      # @param canvas [Sevgi::Graphics::Canvas, nil] source canvas whose identity should be preserved
       # @return [void]
       # @raise [Sevgi::ArgumentError] when either argument is not a ruler
-      def initialize(x:, y:)
-        ArgumentError.("Arguments must be Ruler objects") unless [x, y].all?(Ruler)
+      # @raise [Sevgi::ArgumentError] when the source canvas does not match the ruler spans
+      # @raise [Sevgi::ArgumentError] when either ruler fits no interval
+      def initialize(x:, y:, canvas: nil)
+        validate_axes(x, y)
+        validate_canvas(canvas, x, y)
 
-        @x = X.new(x, y)
-        @y = Y.new(x, y)
+        @source = canvas
+        @x = X.send(:new, x, y)
+        @y = Y.send(:new, x, y)
 
         super(Geometry::Rect[@x.u, @y.u], nx: @x.n, ny: @y.n)
       end
 
-      # Returns a graphics canvas matching the rulers and computed margins.
+      # Returns a graphics canvas matching the ruler spans and fitted margins.
+      # Horizontal ruler margins become the canvas left/right margins; vertical
+      # ruler margins become its top/bottom margins.
+      # @example Build a drawing with the fitted canvas
+      #   x = Sevgi::Sundries::Ruler.new(brut: 80, unit: 1, multiple: 10, margins: [5])
+      #   y = Sevgi::Sundries::Ruler.new(brut: 50, unit: 1, multiple: 10, margins: [5])
+      #   grid = Sevgi::Sundries::Grid[x, y]
+      #   drawing = Sevgi::Graphics.SVG(:inkscape, grid.canvas) do
+      #     Draw grid.x.major.lines, class: %w[guide horizontal]
+      #     Draw grid.y.major.lines, class: %w[guide vertical]
+      #   end
+      #   drawing.Render
       # @return [Sevgi::Graphics::Canvas]
       def canvas
+        margins = [y.start, x.finish, y.finish, x.start]
+        return @source.with(margins:) if @source
+
         Graphics::Canvas.new(
           **Graphics::Paper[x.brut, y.brut].to_h,
-          margins: Graphics::Margin[y.margin, x.margin].to_a
+          margins:
         )
       end
 
@@ -52,17 +101,19 @@ module Sevgi
       # @return [Float]
       def width = x.d
 
-      # Axis wrapper exposing grid line queries for one ruler direction.
+      # Axis wrapper exposing grid line queries for one line direction.
       class Axis < DelegateClass(Ruler)
-        # Returns the major line query.
+        private_class_method :new
+
+        # Returns lines placed at the perpendicular ruler's major distances.
         # @return [Sevgi::Sundries::Grid::Axis::Major]
         attr_reader :major
 
-        # Returns the midpoint line query.
+        # Returns lines placed at the perpendicular ruler's halfway distances.
         # @return [Sevgi::Sundries::Grid::Axis::Halve]
         attr_reader :halve
 
-        # Returns the minor line query.
+        # Returns lines placed at the perpendicular ruler's minor distances.
         # @return [Sevgi::Sundries::Grid::Axis::Minor]
         attr_reader :minor
 
@@ -70,20 +121,24 @@ module Sevgi
         # @param this [Sevgi::Sundries::Ruler] ruler represented by this axis
         # @param other [Sevgi::Sundries::Ruler] ruler used for perpendicular tick locations
         # @return [void]
+        # @api private
         def initialize(this, other)
           super(this)
 
-          @major = Major.new(self, other)
-          @halve = Halve.new(self, other)
-          @minor = Minor.new(self, other)
+          @major = Major.send(:new, self, other)
+          @halve = Halve.send(:new, self, other)
+          @minor = Minor.send(:new, self, other)
         end
 
         # Memoized grid line query for an axis.
         class Query
+          private_class_method :new
+
           # Creates a query.
           # @param this [Sevgi::Sundries::Grid::Axis] axis receiving generated lines
           # @param other [Sevgi::Sundries::Ruler] perpendicular ruler supplying tick distances
           # @return [void]
+          # @api private
           def initialize(this, other) = (@this, @other = this, other)
 
           # Returns grid line endpoints as coordinate pairs.
@@ -99,7 +154,7 @@ module Sevgi
           # Returns generated grid lines.
           # The memoized collection is frozen and must be treated as immutable.
           # @return [Array<Sevgi::Geometry::Line>] frozen lines
-          def lines = @lines ||= lines!.freeze
+          def lines = @lines ||= build.freeze
 
           private
 
@@ -108,23 +163,23 @@ module Sevgi
 
         # Major grid line query.
         class Major < Query
-          # Returns lines at major tick distances.
-          # @return [Array<Sevgi::Geometry::Line>]
-          def lines! = other.ds.map { this.line_at(it) }
+          private
+
+          def build = other.ds.map { this.line_at(it) }
         end
 
         # Midpoint grid line query.
         class Halve < Query
-          # Returns lines at midpoint tick distances.
-          # @return [Array<Sevgi::Geometry::Line>]
-          def lines! = other.hs.map { this.line_at(it) }
+          private
+
+          def build = other.hs.map { this.line_at(it) }
         end
 
         # Minor grid line query.
         class Minor < Query
-          # Returns lines at minor tick distances.
-          # @return [Array<Sevgi::Geometry::Line>]
-          def lines! = other.ms.map { this.line_at(it) }
+          private
+
+          def build = other.ms.map { this.line_at(it) }
         end
       end
 
@@ -146,6 +201,7 @@ module Sevgi
         # @param this [Sevgi::Sundries::Ruler] horizontal ruler
         # @param other [Sevgi::Sundries::Ruler] vertical ruler
         # @return [void]
+        # @api private
         def initialize(this, other) = super(other, this)
 
         # Returns the base vertical line for this axis.
@@ -157,6 +213,22 @@ module Sevgi
         # @return [Sevgi::Geometry::Line]
         def line_at(x) = line.at([x, 0.0])
       end
+
+      private
+
+      def validate_axes(x, y)
+        ArgumentError.("Arguments must be Ruler objects") unless [x, y].all?(Ruler)
+        ArgumentError.("Grid rulers must fit at least one interval") unless x.n.positive? && y.n.positive?
+      end
+
+      def validate_canvas(canvas, x, y)
+        return unless canvas
+
+        ArgumentError.("Grid canvas must match the ruler spans") unless canvas.is_a?(Graphics::Canvas)
+        return if canvas.width == x.brut && canvas.height == y.brut
+
+        ArgumentError.("Grid canvas must match the ruler spans")
+      end
     end
   end
 end

data/lib/sevgi/sundries/ruler.rb

@@ -5,15 +5,20 @@ module Sevgi
     # A one-dimensional interval divided into equal units.
     #
     # The compact reader names are part of the domain vocabulary:
-    # `u` is the unit length, `n` is the interval count, `d` is total
-    # distance, and `h` is the midpoint distance.
+    # `u` is the unit length, `n` is the interval count, and `d` is total
+    # distance. `ds` includes both endpoints, while `hs` contains one halfway
+    # distance per interval. These compact names are intended to read as
+    # formulas in layout code rather than as general-purpose collection names.
     #
     # @example Interval geometry
-    #   # <---------------- d = n x u ---------------->
-    #   # |---------+---------+---------+---------|
-    #   #           <--- u --->
     #   interval = Sevgi::Sundries::Interval[3, 4]
+    #   interval.u # => 3.0
+    #   interval.n # => 4
     #   interval.d # => 12.0
+    # @example Query major and halfway distances
+    #   interval = Sevgi::Sundries::Interval[3, 4]
+    #   interval.ds # => [0.0, 3.0, 6.0, 9.0, 12.0]
+    #   interval.hs # => [1.5, 4.5, 7.5, 10.5]
     class Interval
       # Builds an interval using bracket syntax.
       # @param e [Numeric, #length] unit length or an object exposing length
@@ -149,21 +154,42 @@ module Sevgi
     # Fits a repeated interval into a broader span with computed margins.
     #
     # A ruler stores both the fitted major interval and the source subinterval.
-    # The compact reader names mirror {Interval}: `brut` is the full available
-    # span, `sd/su/sn` describe the subinterval, and `waste` is distributed as
-    # equal margins.
+    # `brut` is the full available span. `unit * multiple` becomes the major
+    # interval, and `sd/su/sn` describe that source subinterval. Requested
+    # margins are minimums: leftover space is split between them while their
+    # start/end difference is preserved. The fitted `d` excludes those margins;
+    # `waste` includes them and any remainder.
     #
     # @example Ruler geometry
-    #   # <--------- d = n x sd ---------><--- waste = 2 x margin --->
-    #   # <----- u = unit x multiple ----->
-    #   # <---------------- brut ---------------->
     #   ruler = Sevgi::Sundries::Ruler.new(unit: 1, multiple: 10, brut: 150)
-    #   ruler.d # => 150.0
+    #   ruler.su # => 1.0
+    #   ruler.sn # => 10
+    #   ruler.u  # => 10.0
+    #   ruler.n  # => 15
+    #   ruler.d  # => 150.0
+    # @example Fit whole major intervals inside minimum margins
+    #   ruler = Sevgi::Sundries::Ruler.new(brut: 103, unit: 1, multiple: 10, margins: [5])
+    #   ruler.n       # => 9
+    #   ruler.margins # => [6.5, 6.5]
+    #   ruler.waste   # => 13.0
+    # @example Preserve an asymmetric margin difference
+    #   ruler = Sevgi::Sundries::Ruler.new(brut: 100, unit: 1, multiple: 10, margins: [5, 15])
+    #   ruler.margins # => [5.0, 15.0]
+    #   ruler.ds.last # => 80.0
+    # @see Sevgi::Sundries::Grid
     class Ruler < Interval
       # Returns the full available span before fitting.
       # @return [Float]
       attr_reader :brut
 
+      # Returns the fitted margin after the interval.
+      # @return [Float]
+      attr_reader :finish
+
+      # Returns the fitted margin before the interval.
+      # @return [Float]
+      attr_reader :start
+
       # Returns the source subinterval.
       # @return [Sevgi::Sundries::Interval]
       attr_reader :sub
@@ -172,7 +198,7 @@ module Sevgi
       # @param brut [Numeric] full available span
       # @param unit [Numeric] subinterval unit length
       # @param multiple [Integer] number of subinterval units per major interval
-      # @param margin [Numeric] minimum margin on each side
+      # @param margins [Array<Numeric>] one symmetric or two start/end minimum margins
       # @return [void]
       # @raise [Sevgi::ArgumentError] when brut is not numeric
       # @raise [Sevgi::ArgumentError] when brut is not finite
@@ -181,31 +207,35 @@ module Sevgi
       # @raise [Sevgi::ArgumentError] when unit is not finite
       # @raise [Sevgi::ArgumentError] when unit is not positive
       # @raise [Sevgi::ArgumentError] when multiple is not a positive integer
-      # @raise [Sevgi::ArgumentError] when margin is not numeric
-      # @raise [Sevgi::ArgumentError] when margin is not finite
-      # @raise [Sevgi::ArgumentError] when margin is negative
+      # @raise [Sevgi::ArgumentError] when margins does not contain one or two values
+      # @raise [Sevgi::ArgumentError] when a margin is not numeric
+      # @raise [Sevgi::ArgumentError] when a margin is not finite
+      # @raise [Sevgi::ArgumentError] when a margin is negative
       # @raise [Sevgi::ArgumentError] when the fitting span is negative
-      def initialize(brut:, unit:, multiple:, margin: 0.0)
+      def initialize(brut:, unit:, multiple:, margins: [0.0])
         @brut = non_negative_number(brut, "Ruler brut")
         unit = positive_number(unit, "Ruler unit")
         multiple = positive_integer(multiple, "Ruler multiple")
-        margin = non_negative_number(margin, "Ruler margin")
         @sub = Interval.new(unit, multiple)
+        span, start, finish = fitting_span(margins)
 
-        n = divide(unit:, multiple:, brut: @brut, margin:)
-
-        ArgumentError.("Ruler fitting span must not be negative") if n.negative?
+        n = divide(unit:, multiple:, span:)
 
         super(@sub, n)
+        @start, @finish = fitted_margins(start, finish, span)
       end
 
       # Returns a ruler where the source subinterval is flattened into units.
+      # @example Expand major intervals into individual units
+      #   ruler = Sevgi::Sundries::Ruler.new(brut: 103, unit: 1, multiple: 10, margins: [5])
+      #   ruler.expand.n # => 90
+      #   ruler.ms.size  # => 91
       # @return [Sevgi::Sundries::Ruler]
-      def expand = self.class.new(unit: sub.u, multiple: 1, brut: d + waste, margin:)
+      def expand = self.class.new(unit: sub.u, multiple: 1, brut: d + waste, margins:)
 
-      # Returns the computed margin after fitting.
-      # @return [Float]
-      def margin = @margin ||= waste / 2.0
+      # Returns fitted start and finish margins.
+      # @return [Array<Float>] frozen margin pair
+      def margins = @margins ||= [start, finish].freeze
 
       # Returns minor tick distances across the fitted span.
       # The memoized collection is frozen and must be treated as immutable.
@@ -228,18 +258,48 @@ module Sevgi
       # @return [Float]
       def su = @sub.u
 
+      private
+
+      def fitted_margins(start, finish, span)
+        extra = (span - d) / 2.0
+        [start + extra, finish + extra]
+      end
+
+      def fitting_span(margins)
+        start, finish = margin_pair(margins)
+        span = brut - start - finish
+        ArgumentError.("Ruler fitting span must not be negative") if span.negative?
+
+        [span, start, finish]
+      end
+
+      def margin_pair(values)
+        unless values.is_a?(::Array) && [1, 2].include?(values.size)
+          ArgumentError.("Ruler margins must contain one or two values")
+        end
+
+        values = [values.first, values.first] if values.one?
+        values.map { non_negative_number(it, "Ruler margin") }
+      end
+
       protected
 
       # Computes the number of major intervals fitting in the available span.
       # @param unit [Numeric] subinterval unit length
       # @param multiple [Integer] number of subinterval units per major interval
-      # @param brut [Numeric] full available span
-      # @param margin [Numeric] minimum margin on each side
+      # @param span [Numeric] span available after margins
       # @return [Integer]
-      def divide(unit:, multiple:, brut:, margin:) = F.count(brut - (2 * margin), unit * multiple)
+      def divide(unit:, multiple:, span:) = F.count(span, unit * multiple)
     end
 
     # Ruler variant that always chooses an even number of major intervals.
+    #
+    # If ordinary fitting produces an odd count, one complete major interval is
+    # removed and the additional space is distributed through the margins.
+    # @example Reserve symmetric waste when an odd count would fit
+    #   ruler = Sevgi::Sundries::RulerEven.new(brut: 50, unit: 1, multiple: 10)
+    #   ruler.n       # => 4
+    #   ruler.margins # => [5.0, 5.0]
     class RulerEven < Ruler
       protected
 

data/lib/sevgi/sundries/tile.rb

@@ -3,6 +3,25 @@
 module Sevgi
   module Sundries
     # Repeats a geometry element over a rectangular row and column layout.
+    #
+    # The source element's bounding-box width and height become the cell pitch.
+    # Indexing is row-first: `tile[row][column]`. Generated cells and collection
+    # snapshots are immutable geometry values; no SVG elements are created.
+    # @example Address cells by row and column
+    #   cell = Sevgi::Geometry::Rect[8, 4]
+    #   tile = Sevgi::Sundries::Tile.new(cell, position: [10, 20], nx: 3, ny: 2)
+    #   tile[1][2].position.deconstruct # => [26.0, 24.0]
+    # @example Inspect the complete, row, and column bounds
+    #   cell = Sevgi::Geometry::Rect[8, 4]
+    #   tile = Sevgi::Sundries::Tile.new(cell, position: [10, 20], nx: 3, ny: 2)
+    #   [tile.box.approx.width, tile.box.approx.height] # => [24.0, 8.0]
+    #   tile.rowbox(1).position.deconstruct # => [10.0, 24.0]
+    #   tile.colbox(2).position.deconstruct # => [26.0, 20.0]
+    # @example Iterate by rows or columns
+    #   tile = Sevgi::Sundries::Tile.new(Sevgi::Geometry::Rect[8, 4], nx: 3, ny: 2)
+    #   tile.each_row.map(&:size) # => [3, 3]
+    #   tile.each_col.map(&:size) # => [2, 2, 2]
+    # @see Sevgi::Graphics::Mixtures::Tile
     class Tile
       include Enumerable
 

data/lib/sevgi/sundries/version.rb

@@ -3,6 +3,6 @@
 module Sevgi
   module Sundries
     # Component version.
-    VERSION = "0.95.0"
+    VERSION = "0.98.2"
   end
 end

data/lib/sevgi/sundries.rb

@@ -15,9 +15,18 @@ require_relative "sundries/version"
 module Sevgi
   # Layout, tiling, grid, and export helpers shared by Sevgi consumers.
   #
-  # This component loads its eager public surfaces directly. `Ruler`, `Tile`, and `Grid` therefore require
-  # `sevgi-function`, `sevgi-geometry`, and `sevgi-graphics` as runtime dependencies of the `sevgi-sundries` gem.
-  # Native PDF/PNG export gems are optional and loaded only by {Export} when export is used.
+  # {Ruler} fits repeatable distances into a span; {Grid} combines two rulers
+  # and exposes drawable lines; {Tile} repeats geometry by rows and columns.
+  # These layout values can be computed without an SVG document and then passed
+  # to Graphics. Native PDF/PNG dependencies remain lazy and are loaded only by
+  # {Export}.
+  # @example Load the component and build a tiled geometry layout
+  #   require "sevgi/sundries"
+  #
+  #   cell = Sevgi::Geometry::Rect[8, 4]
+  #   Sevgi::Sundries::Tile.new(cell, nx: 3, ny: 2).box.deconstruct
+  # @see Sevgi::Graphics::Canvas
+  # @see https://sevgi.roktas.dev/sundries/ Sundries guide
   module Sundries
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sevgi-sundries
 version: !ruby/object:Gem::Version
-  version: 0.95.0
+  version: 0.98.2
 platform: ruby
 authors:
 - Recai Oktaş
@@ -15,43 +15,43 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.95.0
+        version: 0.98.2
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.95.0
+        version: 0.98.2
 - !ruby/object:Gem::Dependency
   name: sevgi-geometry
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.95.0
+        version: 0.98.2
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.95.0
+        version: 0.98.2
 - !ruby/object:Gem::Dependency
   name: sevgi-graphics
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.95.0
+        version: 0.98.2
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.95.0
-description: Enhances the Sevgi toolkit with helper objects.
+        version: 0.98.2
+description: Includes grid, ruler, tile, and optional PDF or PNG export support.
 email: roktas@gmail.com
 executables: []
 extensions: []
@@ -90,7 +90,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.11
+rubygems_version: 4.0.16
 specification_version: 4
-summary: Various instrument objects for the Sevgi toolkit.
+summary: Layout helpers and export tools for Sevgi.
 test_files: []