sevgi-sundries 0.98.2 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7df3ccce8a77f50c584bd9ced3fec7fa19c3efb7c458d8dc248ca3629666fca3
-  data.tar.gz: 690408c4e42c34eb5fe500d405a6f2532c9b7f1b6350784d176ba77f40135ea8
+  metadata.gz: 31d7fd62cc7b0a3897e7a33e780d9ee367e1e782e5022eb5caabacd87633f98c
+  data.tar.gz: c639aa1e07d51c657d8b97400bf9a0696d60a697e87bb7eca94db5d7be5a9b08
 SHA512:
-  metadata.gz: c2c0a0062705f0c9dd55a0cef7093965a14cb9ce5e9f55ad9ca5f72485f715220fd8e9fdd616e707bf21eb3b198cb5011068aee9fff351c4e55e1aea5b03264a
-  data.tar.gz: 72ef749c915cc8782e313292a5da66960f5c50dce49cc071fa2492de97d2d948f3f28f05475290daf979e29247f9ae61a63e347077ceb1a923ec16746e7ddaad
+  metadata.gz: 4dad57c233fc530511b8385d3aedac7a8884957ca57472b56befcbd19561c193f9001c1c26442d99ef43e60ae4e452b2da0a2a27f1ef42a3b6f2f2a15201d533
+  data.tar.gz: 9d49982dabad9bb3cce57b38fa3e8bc229ce2b105671505e0a10dfe32d6fbe7c7cf0cad5e7a85d23b9d301b6981b409e49d7e039d83f4614dd9bc593ba6dcda3

data/CHANGELOG.md

@@ -5,6 +5,120 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## Unreleased
 
+## 1.1.0 - 2026-10-29
+
+### Added
+
+- `Classes` returns an element's distinct CSS class names without changing the element; `Classify` shares its attribute normalization.
+- Generic document-local Style declarations with `Target`, `Param`, `Group`, and `Profiles`, and optional prepared PDF export through the native Mainz CLI.
+- Backend-independent `fallback: false` for export failures and `F.executable` for executable path lookup.
+- `F.path` for path validation and expansion, and `F.output_path` for default output names and directory targets.
+
+### Changed
+
+- Moved Graphics XML validation into auxiliary helpers and kept built-in paper dimensions in `Paper`.
+- Shared path validation between Graphics writers and Sundries exports while preserving output paths and error messages.
+
+### Fixed
+
+- Stamp code placeholders in nested and shared PDF Forms, with cycle-safe resource traversal.
+
+## 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
 
 ### Fixed
@@ -212,7 +326,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

@@ -17,11 +17,52 @@ require "sevgi/sundries"
 ## Example
 
 ```ruby
-rect = Sevgi::Geometry::Rect[3, 5]
-tile = Sevgi::Sundries::Tile.new(rect)
-tile.box.height
+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.canvas.margin.to_a # => [5.0, 5.0, 5.0, 5.0]
+```
+
+Rulers, grids, and tiles are inspectable Ruby values. They create no SVG elements by themselves. Pass their geometry
+to Sevgi Graphics when the document needs it.
+
+## Prepared PDF export
+
+Sevgi uses the native Mainz CLI for SVG sources with a Style declaration.
+Mainz receives private temporary files through argument arrays and publishes one prepared PDF.
+Successful preparation replaces the destination atomically.
+Parallel calls use separate temporary directories and share no producer state.
+
+```ruby
+require "sevgi/sundries"
+
+Sevgi::Sundries::Export.call(svg, "drawing.pdf", style: declaration)
+Sevgi::Sundries::Export.call(svg, "prepared.pdf", style: declaration, fallback: false)
+Sevgi::Sundries::Mainz.produce(svg, "prepared.pdf", declaration: declaration)
+Sevgi::Sundries::Mainz.available?
+```
+
+`declaration` is a JSON-compatible Hash. `drawing.Style` returns its deeply frozen Hash representation.
+The default `fallback: true` warns and uses ordinary PDF export if Mainz cannot prepare the document.
+`fallback: false` raises `Sevgi::Sundries::Mainz::Error` if preparation fails. An unstyled document uses ordinary export.
+`Mainz.produce` always requires preparation and uses the same export validation.
+Invalid arguments and filesystem failures remain errors in both modes.
+Interrupts cancel export without fallback.
+CSS insertion and the source callback run once, including after a fallback.
+
+Mainz is optional. Install its native `mainz` executable on `PATH` to enable preparation.
+Install [Mainz 1.0.0](https://github.com/roktas/mainz/releases/tag/v1.0.0) through Homebrew:
+
+```sh
+brew install roktas/tap/mainz
 ```
 
+Prepared export invokes the CLI without the `cairo`, `rsvg2`, and `hexapdf` Ruby gems.
+Ordinary PDF/PNG export and PDF stamping retain their optional Ruby dependencies.
+`Mainz.fingerprint` returns the executable digest and native dependency report for output caches, or nil when Mainz is absent.
+
 ## Ruby compatibility
 
 Requires Ruby 3.4.0 or newer. CI verifies the current Ruby 3.4 release and the development Ruby from `.ruby-version`.
@@ -31,7 +72,9 @@ Requires Ruby 3.4.0 or newer. CI verifies the current Ruby 3.4 release and the d
 Basic ruler, grid, and tile helpers need only Ruby dependencies. Installing `sevgi-sundries` does not install native
 export gems.
 
-PDF/PNG export helpers load the optional Ruby gems `cairo`, `rsvg2`, and `hexapdf` only when export is used. Install
+The `a5_on_a4` helpers require the `pdfcpu` command. They use its built-in defaults without personal pdfcpu configuration.
+
+Ordinary PDF/PNG export helpers load the optional Ruby gems `cairo`, `rsvg2`, and `hexapdf` only when export is used. Install
 their system libraries and gems separately:
 
 ```sh

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

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Sevgi
+  module Sundries
+    module Export
+      # Validated inputs shared by ordinary and prepared export.
+      # @api private
+      class Input
+        attr_reader :dimensions, :fallback, :style, :svg
+
+        def initialize(svg, options, &block)
+          @fallback = options.fetch(:fallback)
+          ArgumentError.("Export fallback must be true or false") unless [true, false].any? { it.equal?(fallback) }
+          @dimensions = %i[width height dpi].to_h do |key|
+            [key, dimension(options[key], key.to_s, optional: key != :dpi)]
+          end
+          @style = declaration(options[:style])
+          @svg = source(svg, options[:css], &block).dup.freeze
+        end
+
+        private
+
+        def declaration(value)
+          return if value.nil?
+          ArgumentError.("Export Style must be a Hash") unless value.is_a?(::Hash)
+          JSON.generate(value, strict: true, max_nesting: 32).freeze
+        rescue JSON::JSONError => e
+          ArgumentError.("Invalid Style JSON: #{e.message}")
+        end
+
+        def source(svg, css)
+          ArgumentError.("SVG content must be a String") unless svg.is_a?(String)
+          css = stylesheet(css)
+          svg = Export.send(:styled, svg, css) if css
+          svg = yield(svg) if block_given?
+          ArgumentError.("SVG content must be a String") unless svg.is_a?(String)
+          svg
+        end
+
+        def stylesheet(css)
+          return if css.nil?
+          ArgumentError.("Export CSS must be a String") unless css.is_a?(String)
+          ArgumentError.("Export CSS must be valid text") unless css.valid_encoding?
+          css unless css.strip.empty?
+        end
+
+        # Numeric coercion and finite positive admission are one boundary check.
+        # rubocop:disable-next Metrics/CyclomaticComplexity
+        def dimension(value, field, optional: true)
+          return if value.nil? && optional
+          ExportError.(dimension_error(field)) unless value.is_a?(::Numeric)
+          number = begin
+            value.to_f
+          rescue ::StandardError => e
+            ExportError.(dimension_error(field, e.message))
+          end
+          ExportError.(dimension_error(field)) unless number.is_a?(::Float) && number.finite? && number.positive?
+          number
+        end
+
+        def dimension_error(field, detail = nil)
+          message = [
+            (%w[width height].include?(field) ? "Invalid export dimensions" : "Invalid export #{field}"),
+            detail
+          ]
+          message.compact.join(": ")
+        end
+      end
+
+      private_constant :Input
+    end
+  end
+end

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

@@ -13,42 +13,13 @@ module Sevgi
   module Sundries
     module Export
       %i[
-        call
         stamp
         stamp!
       ].each { remove_method(it) if method_defined?(it) }
 
-      # Exports SVG source to a PDF or PNG file using librsvg and Cairo.
-      # @param svg [String] SVG source content
-      # 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; 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 [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)
-        output = output_path(output)
-        format = format_for(format, output)
-        width = dimension(width, "width")
-        height = dimension(height, "height")
-        dpi = dimension(dpi, "dpi", optional: false)
-        ArgumentError.("Export CSS must be a String") unless css.nil? || css.is_a?(String)
-
-        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)
-
+      # Renders validated, transformed SVG through librsvg and Cairo.
+      # @api private
+      def render(svg, output, format:, width:, height:, dpi:)
         renderer = Renderer.method(format)
 
         begin
@@ -81,6 +52,30 @@ module Sevgi
 
         output
       end
+      private :render
+
+      # @api private
+      def stamp_forms(document, stamp:, placeholder:)
+        pending = document.pages.flat_map { |page| page[:Resources][:XObject]&.each&.map { |_name, value| value } || [] }
+        seen = {}
+        replacements = 0
+        until pending.empty?
+          form = pending.pop
+          next unless form[:Subtype] == :Form
+          identity = [form.oid, form.gen]
+          next if seen[identity]
+          seen[identity] = true
+          objects = form[:Resources]&.[](:XObject)
+          pending.concat(objects ? objects.each.map { |_name, value| value } : [])
+          data, count = stamp_stream(form.stream, stamp:, placeholder:)
+          next if count.zero?
+          replacements += count
+          form.stream = data
+          form.set_filter(:FlateDecode)
+        end
+        replacements
+      end
+      private :stamp_forms
 
       # Replaces exact placeholder text objects in PDF streams.
       # The placeholder must appear as a PDF literal string in a white text object matching the export stamp pattern.
@@ -92,26 +87,21 @@ module Sevgi
       # @param placeholder [String] placeholder text to replace
       # @return [Boolean] true when at least one matching placeholder was replaced
       # @raise [Sevgi::Sundries::Export::ExportError] when the PDF cannot be read, rewritten, or stamped
-      # @note Streams with unbalanced graphics-state or text-object operators are left unchanged.
+      # @note Pages with inline images, unknown operators, or unbalanced graphics-state/text-object operators are left unchanged.
       def stamp(infile, outfile, stamp:, placeholder:)
         doc = HexaPDF::Document.open(infile)
         replacements = 0
 
         doc.pages.each do |page|
-          Array(page[:Contents]).each do |ref|
-            obj = doc.object(ref)
-            next unless obj.respond_to?(:stream)
-
-            data, count = stamp_stream(obj.stream, stamp:, placeholder:)
-            next if count.zero?
+          data, count = stamp_stream(page.contents, stamp:, placeholder:)
+          next if count.zero?
 
-            replacements += count
-
-            obj.stream = data
-            obj.set_filter(:FlateDecode)
-          end
+          replacements += count
+          page.contents = data
+          doc.deref(page[:Contents]).set_filter(:FlateDecode)
         end
 
+        replacements += stamp_forms(doc, stamp:, placeholder:)
         doc.write(outfile, optimize: true) if replacements.positive?
         replacements.positive?
       rescue HexaPDF::Error, ::SystemCallError => e
@@ -126,7 +116,7 @@ module Sevgi
       # @param placeholder [String] placeholder text to replace
       # @return [Boolean] true when at least one matching placeholder was replaced
       # @raise [Sevgi::Sundries::Export::ExportError] when the PDF cannot be read, rewritten, stamped, or replaced
-      # @note Streams with unbalanced graphics-state or text-object operators are left unchanged.
+      # @note Pages with inline images, unknown operators, or unbalanced graphics-state/text-object operators are left unchanged.
       def stamp!(infile, stamp:, placeholder:)
         temp = Tempfile.new(%w[stamp .pdf], File.dirname(infile))
         stamped = stamp(infile, temp.path, stamp:, placeholder:)
@@ -185,7 +175,6 @@ module Sevgi
           serializer = HexaPDF::Serializer.new
           operands = []
           state = {
-            fill_span: nil,
             fill_white: false,
             font_size: nil,
             in_text: false,
@@ -206,8 +195,12 @@ module Sevgi
               next
             end
 
+            # Inline image bytes are not PDF tokens; never interpret them as operators.
+            operator = object.to_sym
+            return [{}, 0] if operator == :BI || !HexaPDF::Content::Processor::OPERATOR_MESSAGE_NAME_MAP.key?(operator)
+
             count += process_operator(
-              object.to_sym,
+              operator,
               operands,
               finish,
               data,
@@ -227,11 +220,13 @@ module Sevgi
         def process_operator(operator, operands, finish, data, stamp:, placeholder:, serializer:, state:, replacements:)
           case operator
           when :q
-            state[:stack] << state.values_at(:fill_span, :fill_white, :font_size)
+            state[:stack] << state.values_at(:fill_white, :font_size)
           when :Q
             state[:stack].any? ? restore_state(state) : state[:valid] = false
           when :rg
-            set_fill_state(state, operands, finish)
+            set_fill_state(state, operands)
+          when :g, :k, :cs, :sc, :scn
+            state[:fill_white] = false
           when :BT
             state[:valid] = false if state[:in_text]
             state[:in_text] = true
@@ -245,6 +240,7 @@ module Sevgi
               operator,
               operands,
               data,
+              operator_finish: finish,
               stamp:,
               placeholder:,
               serializer:,
@@ -257,31 +253,38 @@ module Sevgi
         end
 
         def restore_state(state)
-          state[:fill_span], state[:fill_white], state[:font_size] = state[:stack].pop
+          state[:fill_white], state[:font_size] = state[:stack].pop
         end
 
-        def set_fill_state(state, operands, finish)
+        def set_fill_state(state, operands)
           state[:fill_white] = operands.size == 3 && operands.all? { |value, _start, _finish| value == 1 }
-          state[:fill_span] = [operands.first[1], finish] if state[:fill_white]
-          state[:fill_span] = nil unless state[:fill_white]
         end
 
-        def add_text_replacement(operator, operands, data, stamp:, placeholder:, serializer:, state:, replacements:)
+        def add_text_replacement(
+          operator,
+          operands,
+          data,
+          operator_finish:,
+          stamp:,
+          placeholder:,
+          serializer:,
+          state:,
+          replacements:
+        )
           replacement = text_replacement(data, operator, operands, stamp:, placeholder:, serializer:, state:)
           return 0 unless replacement
 
-          start, finish, text = replacement
-          replacements[[start, finish]] = text
-          add_color_replacement(data, state, replacements)
+          start, text_finish, text = replacement
+          color_start = operands.first.fetch(1)
+          text = " 0.101961 0.101961 0.101961 rg#{text}" if start == color_start
+          replacements[[start, text_finish]] = text
+          add_color_replacement(color_start, replacements) unless start == color_start
+          replacements[[operator_finish, operator_finish]] ||= " 1 1 1 rg"
           1
         end
 
-        def add_color_replacement(data, state, replacements)
-          return unless state[:fill_span]
-
-          color_start, color_finish = state[:fill_span]
-          prefix = data[color_start...color_finish].to_s[/\A\s*/]
-          replacements[[color_start, color_finish]] ||= "#{prefix}0.101961 0.101961 0.101961 rg"
+        def add_color_replacement(start, replacements)
+          replacements[[start, start]] ||= " 0.101961 0.101961 0.101961 rg"
         end
 
         def text_replacement(data, operator, operands, stamp:, placeholder:, serializer:, state:)
@@ -309,45 +312,6 @@ module Sevgi
       class << self
         private
 
-        def output_path(output)
-          ArgumentError.("Export output must be provided") if output.nil?
-
-          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 or path-like object: #{e.message}")
-        end
-
-        def dimension(value, field, optional: true)
-          return if value.nil? && optional
-          ExportError.(dimension_error(field)) unless value.is_a?(::Numeric)
-
-          number = begin
-            value.to_f
-          rescue ::StandardError => e
-            ExportError.(dimension_error(field, e.message))
-          end
-
-          ExportError.(dimension_error(field)) unless number.is_a?(::Float) && number.finite? && number.positive?
-
-          number
-        end
-
-        def dimension_error(field, detail = nil)
-          message = [
-            (%w[width height].include?(field) ? "Invalid export dimensions" : "Invalid export #{field}"),
-            detail
-          ]
-          message.compact.join(": ")
-        end
-
         def intrinsic_size(handle)
           if handle.respond_to?(:intrinsic_dimensions)
             has_width, width, has_height, height, has_viewbox, viewbox = handle.intrinsic_dimensions
@@ -426,18 +390,6 @@ module Sevgi
       module Renderer
         extend self
 
-        # Returns a renderer method for a format.
-        # @param format [Symbol, String, nil] format name
-        # @return [Method, nil]
-        def [](format)
-          case format&.to_sym
-          when :png
-            method(:png)
-          when :pdf
-            method(:pdf)
-          end
-        end
-
         # Renders SVG data to a PDF surface.
         # @param handle [Rsvg::Handle] parsed SVG handle
         # @param output [String] output file path

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

@@ -13,7 +13,9 @@ module Sevgi
       # @raise [Sevgi::Error] when pdfcpu is missing or the command fails
       # @raise [Errno::ENOENT] when the executable cannot be spawned
       # @see https://pdfcpu.io/ pdfcpu
-      def a5_on_a4(infile, outfile) = F.sh!("pdfcpu", "nup", "--", "form:A4L, border:off", outfile, "2", infile)
+      def a5_on_a4(infile, outfile)
+        F.sh!("pdfcpu", "--conf", "disable", "nup", "--", "form:A4L, border:off", outfile, "2", infile)
+      end
 
       # Replaces a PDF file with an A5-on-A4 layout generated by pdfcpu.
       # @param infile [String] PDF file path to modify
@@ -22,8 +24,10 @@ module Sevgi
       # @raise [Errno::ENOENT] when the executable cannot be spawned
       def a5_on_a4!(infile)
         temp = Tempfile.new(%w[output .pdf], File.dirname(infile))
-        a5_on_a4(infile, temp.path)
-        FileUtils.mv(temp.path, infile)
+        outfile = temp.path
+        temp.close!
+        a5_on_a4(infile, outfile)
+        FileUtils.mv(outfile, infile)
       ensure
         temp&.close!
       end

data/lib/sevgi/sundries/export.rb

@@ -3,6 +3,8 @@
 require "sevgi/function"
 
 require_relative "export/system"
+require_relative "export/input"
+require_relative "mainz"
 
 module Sevgi
   module Sundries
@@ -10,17 +12,21 @@ module Sevgi
     #
     # 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. Omit `format:` to infer it from the output suffix;
+    # 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.
+    # Export-only CSS is a last-minute adjustment, not a replacement for document styles or validation. Insertion
+    # requires well-formed SVG ending in an unprefixed `</svg>` followed only by XML whitespace. Self-closing roots,
+    # prefixed roots, and trailing comments are unsupported with CSS. CSS is XML-escaped but not parsed or validated.
+    # The source callback runs after insertion and before ordinary or prepared conversion.
     #
     # @example Export SVG source to a sized PNG
-    #   svg = Sevgi::Graphics.SVG(:minimal) { circle cx: 5, cy: 5, r: 4 }.Render
+    #   svg = Sevgi::Graphics.SVG(width: 10, height: 10) { 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
+    #   svg = Sevgi::Graphics.SVG(width: 10, height: 10) { circle class: "accent", cx: 5, cy: 5, r: 4 }.Render
     #   Sevgi::Sundries::Export.call(svg, "drawing.pdf", css: ".accent { fill: tomato; }")
-    # @see https://sevgi.roktas.dev/sundries/#export Export guide
+    # @see https://sevgi.roktas.dev/output/#export Export guide
     module Export
       # File extensions mapped to export format names.
       # @api private
@@ -47,27 +53,40 @@ module Sevgi
 
       private_constant :NATIVE_COMPONENTS
 
-      # @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
-      #   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] 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 [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, 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)
+      # rubocop:disable Metrics/ParameterLists
+
+      # Exports SVG source through ordinary rendering or optional Mainz preparation.
+      # Style selects Mainz automatically for PDF output. Unstyled documents use ordinary export.
+      # Fallback warns and uses ordinary PDF export after a preparation failure.
+      # CSS and the source callback run once before either backend receives the source.
+      # @param svg [String] SVG source content
+      # @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] 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
+      # @param style [Hash, nil] optional JSON authoring declaration
+      # @param fallback [Boolean] permit ordinary export after prepared export fails
+      # @yield [svg] optional source transformation before rendering
+      # @yieldparam svg [String] SVG source after optional CSS insertion
+      # @yieldreturn [String] SVG source to render
+      # @return [String] expanded output path
+      # @raise [Sevgi::ArgumentError] when the source, path, declaration, or fallback value is invalid
+      # @raise [Sevgi::MissingComponentError] when ordinary export requires unavailable native gems
+      # @raise [Sevgi::Sundries::Export::ExportError] when format, dimensions, CSS insertion, or ordinary rendering fails
+      # @raise [Sevgi::Sundries::Mainz::Error] when preparation fails and fallback is false
+      # @raise [SystemCallError] when the output directory or file cannot be written
+      def call(svg, output, format: nil, width: nil, height: nil, dpi: DEFAULT_DPI, css: nil,
+        style: nil, fallback: true, &block)
+        output = output_path(output)
+        format = format_for(format, output)
+        input = Input.new(svg, {width:, height:, dpi:, css:, style:, fallback:}, &block)
+        return output if format == :pdf && prepared(input, output)
+        native!
+        render(input.svg, output, format:, **input.dimensions)
+      end
+      # rubocop:enable Metrics/ParameterLists
 
       def format_for(format, output)
         if format
@@ -84,10 +103,12 @@ module Sevgi
       end
 
       def styled(svg, css)
-        output = svg.sub("</svg>", "<style>#{css}</style></svg>")
-        ExportError.("Cannot insert CSS: closing svg tag not found") if output == svg
+        ArgumentError.("Export CSS must be valid text") unless css.is_a?(::String) && css.valid_encoding?
+        closing = %r{</svg>[ \t\r\n]*\z}
+        ExportError.("Cannot insert CSS: expected final </svg> root closing tag") unless closing.match?(svg)
 
-        output
+        text = css.gsub(/[&<>]/, "&" => "&amp;", "<" => "&lt;", ">" => "&gt;")
+        svg.sub(closing) { |suffix| "<style>#{text}</style>#{suffix}" }
       end
 
       def normalize_format(format)
@@ -101,6 +122,8 @@ module Sevgi
       private :format_for, :normalize_format, :styled
 
       # Replaces exact placeholder text objects in PDF streams.
+      # The placeholder must be a PDF literal string inside a white text object that matches Sevgi's stamp pattern.
+      # Replacement text is escaped as a PDF literal string. When no match exists, the method writes no output file.
       # @param infile [String] source PDF file path
       # @param outfile [String] destination PDF file path
       # @param stamp [String] replacement text
@@ -112,6 +135,7 @@ module Sevgi
       def stamp(infile, outfile, stamp:, placeholder:) = native!.stamp(infile, outfile, stamp:, placeholder:)
 
       # Replaces exact placeholder text objects inside a PDF file in place.
+      # The input file changes only after at least one exact match produces a nonempty output file.
       # @param infile [String] PDF file path to modify
       # @param stamp [String] replacement text
       # @param placeholder [String] placeholder text to replace
@@ -126,6 +150,26 @@ module Sevgi
       class << self
         private
 
+        def prepared(input, output)
+          return false unless input.style
+          Mainz.send(:write, input, output)
+          true
+        rescue Mainz::Error => e
+          raise unless input.fallback
+          warn("#{e.message}; exporting an ordinary PDF without editable styles")
+          false
+        end
+
+        def output_path(output)
+          ArgumentError.("Export output must be provided") if output.nil?
+          path = F.path(output, context: "Export output")
+          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 or path-like object: #{e.message}")
+        end
+
         def native!
           require_relative "export/native"
 

data/lib/sevgi/sundries/grid.rb

@@ -8,7 +8,7 @@ module Sevgi
     #
     # 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
+    # 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
@@ -54,7 +54,7 @@ module Sevgi
       # 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
+      # @param canvas [Sevgi::Graphics::Canvas, nil] optional source canvas whose identity the grid preserves
       # @return [void]
       # @raise [Sevgi::ArgumentError] when either argument is not a ruler
       # @raise [Sevgi::ArgumentError] when the source canvas does not match the ruler spans
@@ -71,7 +71,7 @@ module Sevgi
       end
 
       # Returns a graphics canvas matching the ruler spans and fitted margins.
-      # Horizontal ruler margins become the canvas left/right margins; vertical
+      # 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])
@@ -130,7 +130,7 @@ module Sevgi
           @minor = Minor.send(:new, self, other)
         end
 
-        # Memoized grid line query for an axis.
+        # Grid line query for an axis.
         class Query
           private_class_method :new
 
@@ -141,18 +141,18 @@ module Sevgi
           # @api private
           def initialize(this, other) = (@this, @other = this, other)
 
-          # Returns grid line endpoints as coordinate pairs.
-          # The outer and nested collections are frozen and must be treated as immutable.
+          # Returns grid line endpoints as coordinate pairs at the active {Sevgi::F} precision.
+          # Each call reads the current thread precision. The outer and nested collections are frozen.
           # @return [Array<Array<Array<Float>>>] frozen coordinate pairs
-          def xys = @xys ||= lines.map { it.points(true).map { |point| point.deconstruct.freeze }.freeze }.freeze
+          def xys = lines.map { it.points(true).map { |point| point.deconstruct.freeze }.freeze }.freeze
 
-          # Returns grid line endpoints as points.
-          # The outer and nested collections are frozen and must be treated as immutable.
+          # Returns grid line endpoints as points at the active {Sevgi::F} precision.
+          # Each call reads the current thread precision. The outer and nested collections are frozen.
           # @return [Array<Array<Sevgi::Geometry::Point>>] frozen point pairs
-          def points = @points ||= lines.map { it.points(true).freeze }.freeze
+          def points = lines.map { it.points(true).freeze }.freeze
 
-          # Returns generated grid lines.
-          # The memoized collection is frozen and must be treated as immutable.
+          # Returns exact generated grid lines.
+          # The collection is computed once and frozen. Use {#points} or {#xys} for precision-rounded coordinates.
           # @return [Array<Sevgi::Geometry::Line>] frozen lines
           def lines = @lines ||= build.freeze
 

data/lib/sevgi/sundries/mainz.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+require "json"
+require "tmpdir"
+
+module Sevgi
+  module Sundries
+    # Optional CLI boundary for Mainz prepared PDF production.
+    module Mainz
+      COMMAND = "mainz"
+      private_constant :COMMAND
+
+      # A missing or unsuccessful Mainz producer.
+      Error = Class.new(::Sevgi::Error)
+
+      # Reports whether the Mainz executable is installed on PATH.
+      # @return [Boolean]
+      def available? = F.executable?(COMMAND)
+
+      # Returns the selected executable's content identity for output caches.
+      # PATH is resolved on each call. Absence returns nil.
+      # @return [Hash{String => Object}, nil] executable SHA-256 and native dependency report
+      # @raise [SystemCallError] when the executable cannot be read
+      # @raise [Sevgi::Sundries::Mainz::Error] when the version command fails or its report is invalid
+      def fingerprint
+        path = F.executable(COMMAND)
+        return unless path
+        process = run(path, "--version")
+        report = JSON.parse(process.out)
+        Error.("Invalid Mainz version report") unless report.is_a?(Hash) && report["contract"] == 1
+        {"sha256" => Digest::SHA256.file(path).hexdigest, "runtime" => report}
+      rescue JSON::ParserError => e
+        Error.("Invalid Mainz version report: #{e.message}")
+      end
+
+      # Produces and atomically replaces one PDF through the native CLI.
+      # Input paths and output staging remain private to this call.
+      # @param svg [String] SVG source
+      # @param output [String, #to_path] destination path
+      # @param declaration [Hash] JSON authoring declaration
+      # @param options [Hash] ordinary export options
+      # @option options [Numeric, nil] :width output width in CSS pixels
+      # @option options [Numeric, nil] :height output height in CSS pixels
+      # @option options [Numeric] :dpi (96.0) positive CSS pixel density
+      # @option options [String, nil] :css export-only CSS
+      # @yield [svg] transforms the source once before production
+      # @yieldparam svg [String] SVG after optional CSS insertion
+      # @yieldreturn [String] source to render
+      # @return [String] expanded destination path
+      # @raise [Sevgi::ArgumentError] when the source, path, or declaration is invalid
+      # @raise [Sevgi::Sundries::Mainz::Error] when Mainz is missing or preparation fails
+      # @raise [SystemCallError] when staging or installation fails
+      def produce(svg, output, declaration:, **options, &block)
+        ArgumentError.("Mainz declaration must be a Hash") unless declaration.is_a?(::Hash)
+        unknown = options.keys - %i[css dpi height width]
+        ArgumentError.("Unknown Mainz option: #{unknown.first}") unless unknown.empty?
+        Export.call(svg, output, format: :pdf, style: declaration, fallback: false, **options, &block)
+      end
+
+      extend self
+
+      class << self
+        private
+
+        def write(input, output)
+          program = F.executable(COMMAND) || Error.("Mainz executable is unavailable")
+          parent = ::File.dirname(output)
+          parent = ::File.dirname(parent) until ::File.directory?(parent)
+          dimensions = input.dimensions.flat_map { |key, value| value.nil? ? [] : ["--#{key}", value.to_s] }
+          ::Dir.mktmpdir(".sevgi-mainz-", parent) do |directory|
+            result = prepare(program, directory, input.svg, input.style, dimensions)
+            install(result, output)
+          end
+          output
+        end
+
+        def prepare(program, directory, svg, declaration, dimensions)
+          source, definitions, result = %w[source.svg style.json output.pdf].map { ::File.join(directory, it) }
+          ::File.binwrite(source, svg)
+          ::File.write(definitions, declaration)
+          run(program, "produce", source, "--declaration", definitions, "--output", result, *dimensions)
+          result
+        end
+
+        def run(*arguments)
+          process = F.sh(*arguments)
+          raise ::Interrupt if Signal.list.values_at("INT", "TERM", "KILL").include?(process.signal) || process.exit_code == 130
+          Error.("Mainz preparation failed: #{process.err}") unless process.ok?
+          process
+        rescue Errno::ENOENT => e
+          Error.("Mainz executable is unavailable: #{e.message}")
+        end
+
+        def install(result, output)
+          unless ::File.file?(result) && !::File.symlink?(result) && ::File.size(result).positive?
+            Error.("Mainz produced no PDF")
+          end
+          ::FileUtils.mkdir_p(::File.dirname(output))
+          ::File.rename(result, output)
+        end
+      end
+    end
+  end
+end

data/lib/sevgi/sundries/ruler.rb

@@ -64,7 +64,7 @@ module Sevgi
       # @raise [Sevgi::ArgumentError] when length is not numeric
       # @raise [Sevgi::ArgumentError] when length is not finite
       # @raise [Sevgi::ArgumentError] when length is not positive
-      def count(length) = (d / positive_number(length, "Interval count length")).to_i
+      def count(length) = F.count(d, positive_number(length, "Interval count length"))
 
       # Returns the total interval distance.
       # @return [Float]
@@ -157,7 +157,7 @@ module Sevgi
     # `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;
+    # start/end difference is preserved. The fitted `d` excludes those margins.
     # `waste` includes them and any remainder.
     #
     # @example Ruler geometry
@@ -225,13 +225,13 @@ module Sevgi
         @start, @finish = fitted_margins(start, finish, span)
       end
 
-      # Returns a ruler where the source subinterval is flattened into units.
+      # Returns a ruler where the source subinterval is flattened into units without refitting the span.
       # @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, margins:)
+      def expand = dup.expand!
 
       # Returns fitted start and finish margins.
       # @return [Array<Float>] frozen margin pair
@@ -244,7 +244,9 @@ module Sevgi
 
       # Returns the unfitted distance distributed outside the fitted span.
       # @return [Float]
-      def waste = @waste ||= brut - d
+      def waste
+        @waste ||= (brut - d).then { it.negative? && d.prev_float <= brut ? 0.0 : it }
+      end
 
       # Returns the source subinterval count.
       # @return [Integer]
@@ -261,7 +263,9 @@ module Sevgi
       private
 
       def fitted_margins(start, finish, span)
-        extra = (span - d) / 2.0
+        extra = span - d
+        extra = 0.0 if extra.negative? && d.prev_float <= span
+        extra /= 2.0
         [start + extra, finish + extra]
       end
 
@@ -284,6 +288,16 @@ module Sevgi
 
       protected
 
+      # Flattens a copied ruler and clears values derived from its old interval.
+      # @api private
+      def expand!
+        @n *= sn
+        @u = su
+        @sub = Interval.new(@u, 1)
+        @d = @ds = @h = @hs = @ms = @nds = @nhs = @waste = nil
+        self
+      end
+
       # 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
@@ -296,7 +310,7 @@ module Sevgi
     #
     # 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
+    # @example Reserve symmetric waste when ordinary fitting produces an odd count
     #   ruler = Sevgi::Sundries::RulerEven.new(brut: 50, unit: 1, multiple: 10)
     #   ruler.n       # => 4
     #   ruler.margins # => [5.0, 5.0]

data/lib/sevgi/sundries/tile.rb

@@ -6,7 +6,7 @@ module Sevgi
     #
     # 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.
+    # 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)
@@ -29,7 +29,7 @@ module Sevgi
       # @return [Sevgi::Geometry::Element]
       attr_reader :element
 
-      # Returns the tile origin.
+      # Returns the upper-left corner of the tile bounds.
       # @return [Sevgi::Geometry::Point]
       attr_reader :position
 
@@ -43,7 +43,7 @@ module Sevgi
 
       # Creates a tile from a source geometry element.
       # @param element [Sevgi::Geometry::Element] geometry element to repeat
-      # @param position [Sevgi::Geometry::Point, Array<Numeric>] tile origin
+      # @param position [Sevgi::Geometry::Point, Array<Numeric>] upper-left corner of the tile bounds
       # @param nx [Integer] number of columns
       # @param ny [Integer] number of rows
       # @return [void]
@@ -57,6 +57,7 @@ module Sevgi
 
         @element = element
         @position = self.class.send(:position, position)
+        @bounds = element.box
 
         @nx = nx
         @ny = ny
@@ -65,20 +66,26 @@ module Sevgi
       # Returns a row by index.
       # @param i [Integer] row index
       # @return [Array<Sevgi::Geometry::Element>, nil]
-      def [](i) = rows[i]
+      # @raise [Sevgi::ArgumentError] when the index is not an Integer
+      def [](i) = row(i)
 
       # Returns the bounding rectangle of the whole tile.
       # @return [Sevgi::Geometry::Rect]
-      def box = @box ||= Geometry::Rect[nx * element.box.width, ny * element.box.height, position:]
+      def box = @box ||= Geometry::Rect[nx * @bounds.width, ny * @bounds.height, position:]
 
       # Returns the first cell in the tile.
       # @return [Sevgi::Geometry::Element]
-      def cell = row.first
+      def cell = @cell ||= cell_at(0, 0)
 
       # Returns the bounding rectangle of a column.
       # @param i [Integer] column index
-      # @return [Sevgi::Geometry::Rect]
-      def colbox(i = 0) = Geometry::Rect[element.box.width, box.height, position: coordinate(0, i)]
+      # Negative indices count from the last column. Out-of-range indices return nil.
+      # @return [Sevgi::Geometry::Rect, nil]
+      # @raise [Sevgi::ArgumentError] when the index is not an Integer
+      def colbox(i = 0)
+        i = index(i, nx)
+        Geometry::Rect[@bounds.width, box.height, position: coordinate(0, i)] if i
+      end
 
       # Returns cells grouped by column.
       # The outer and nested collections are frozen and must be treated as immutable.
@@ -88,7 +95,13 @@ module Sevgi
       # Returns a column by index.
       # @param i [Integer] column index
       # @return [Array<Sevgi::Geometry::Element>, nil]
-      def col(i = 0) = cols[i]
+      # @raise [Sevgi::ArgumentError] when the index is not an Integer
+      def col(i = 0)
+        i = index(i, nx)
+        return unless i
+
+        @cols ? @cols[i] : Array.new(ny) { |j| cell_at(j, i) }.freeze
+      end
 
       # Iterates over rows.
       # @yield [row] each row
@@ -107,17 +120,28 @@ module Sevgi
       # Returns a row by index.
       # @param i [Integer] row index
       # @return [Array<Sevgi::Geometry::Element>, nil]
-      def row(i = 0) = rows[i]
+      # @raise [Sevgi::ArgumentError] when the index is not an Integer
+      def row(i = 0)
+        i = index(i, ny)
+        return unless i
+
+        @rows ? @rows[i] : Array.new(nx) { |j| cell_at(i, j) }.freeze
+      end
 
       # Returns the bounding rectangle of a row.
       # @param i [Integer] row index
-      # @return [Sevgi::Geometry::Rect]
-      def rowbox(i = 0) = Geometry::Rect[box.width, element.box.height, position: coordinate(i)]
+      # Negative indices count from the last row. Out-of-range indices return nil.
+      # @return [Sevgi::Geometry::Rect, nil]
+      # @raise [Sevgi::ArgumentError] when the index is not an Integer
+      def rowbox(i = 0)
+        i = index(i, ny)
+        Geometry::Rect[box.width, @bounds.height, position: coordinate(i)] if i
+      end
 
       # Returns cells grouped by row.
       # The outer and nested collections are frozen and must be treated as immutable.
       # @return [Array<Array<Sevgi::Geometry::Element>>] frozen rows
-      def rows = @rows ||= (0...ny).map { |i| (0...nx).map { |j| element.at(coordinate(i, j)) }.freeze }.freeze
+      def rows = @rows ||= (0...ny).map { |i| (0...nx).map { |j| cell_at(i, j) }.freeze }.freeze
 
       # Iterates over rows.
       # @return [Enumerator, Array<Array<Sevgi::Geometry::Element>>] enumerator without a block, otherwise rows
@@ -125,6 +149,12 @@ module Sevgi
 
       private
 
+      def index(value, count)
+        ArgumentError.("Tile index must be an Integer") unless value.is_a?(::Integer)
+        value += count if value.negative?
+        value if value.between?(0, count - 1)
+      end
+
       # Coerces a public tile position.
       # @param position [Sevgi::Geometry::Point, Array<Numeric>] tile origin
       # @return [Sevgi::Geometry::Point]
@@ -141,7 +171,12 @@ module Sevgi
 
       private_class_method :position
 
-      def coordinate(i, j = 0) = position.translate(j * element.box.width, i * element.box.height)
+      def cell_at(i, j)
+        point = coordinate(i, j)
+        element.translate(point.x - @bounds.position.x, point.y - @bounds.position.y)
+      end
+
+      def coordinate(i, j = 0) = position.translate(j * @bounds.width, i * @bounds.height)
     end
   end
 end

data/lib/sevgi/sundries/version.rb

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

data/lib/sevgi/sundries.rb

@@ -15,8 +15,8 @@ require_relative "sundries/version"
 module Sevgi
   # Layout, tiling, grid, and export helpers shared by Sevgi consumers.
   #
-  # {Ruler} fits repeatable distances into a span; {Grid} combines two rulers
-  # and exposes drawable lines; {Tile} repeats geometry by rows and columns.
+  # {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}.
@@ -26,7 +26,8 @@ module Sevgi
   #   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
+  # @see https://sevgi.roktas.dev/layout/ Layout guide
+  # @see https://sevgi.roktas.dev/output/ Output guide
   module Sundries
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sevgi-sundries
 version: !ruby/object:Gem::Version
-  version: 0.98.2
+  version: 1.1.0
 platform: ruby
 authors:
 - Recai Oktaş
@@ -9,48 +9,62 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
 - !ruby/object:Gem::Dependency
   name: sevgi-function
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.98.2
+        version: 1.1.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.98.2
+        version: 1.1.0
 - !ruby/object:Gem::Dependency
   name: sevgi-geometry
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.98.2
+        version: 1.1.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.98.2
+        version: 1.1.0
 - !ruby/object:Gem::Dependency
   name: sevgi-graphics
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.98.2
+        version: 1.1.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.98.2
+        version: 1.1.0
 description: Includes grid, ruler, tile, and optional PDF or PNG export support.
 email: roktas@gmail.com
 executables: []
@@ -62,9 +76,11 @@ files:
 - README.md
 - lib/sevgi/sundries.rb
 - lib/sevgi/sundries/export.rb
+- lib/sevgi/sundries/export/input.rb
 - lib/sevgi/sundries/export/native.rb
 - lib/sevgi/sundries/export/system.rb
 - lib/sevgi/sundries/grid.rb
+- lib/sevgi/sundries/mainz.rb
 - lib/sevgi/sundries/ruler.rb
 - lib/sevgi/sundries/tile.rb
 - lib/sevgi/sundries/version.rb
@@ -90,7 +106,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: Layout helpers and export tools for Sevgi.
 test_files: []