sevgi-geometry 0.98.2 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7928a9adb69da869093c319a3a755110f5e12e5b6f336c949842194c58ffabca
-  data.tar.gz: 35127c296da46e52a74b37b9535a49cf2717b51bad2fa83178734914160ecbec
+  metadata.gz: 5541e9628216ffd94f9d305d00419f6d7d306c6c0250cdece01c04907cf2e504
+  data.tar.gz: 0d1f0f9ea6bb347e8b98e9472c66ac87ddc9a2e512160c73848788ec5b36dc7b
 SHA512:
-  metadata.gz: 4c67d947c34fedd4ac99723bb070413d33300030a50a450cabea9f9bea85aed9837d54d792797b989cd4310bdcfca2988be46bac7087edbf96fa378152982145
-  data.tar.gz: d4f55fbf8282515f524ff9056a02c4e629aa014dcce4435066996bdd2cbd8c9edcb72979ed98d6c6430f8f636722a98686f5e8710e0983461fc32d80ec38c56d
+  metadata.gz: e5c264c3685c2b0034ab38c0ff64d36b53de4adec41df40d98609ce18841cca60922c24d1e0b331b931456a40e9ed519ec806ad566a35f47c68ffd6b4c7ead74
+  data.tar.gz: f053552d2951ab8147cdfb5cbb974b080fd0780885a316f148386fce0d6d2680da3021853772e41b12e84832c742c3536e9df3f9b710c25b838646457846ee03

data/CHANGELOG.md

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

data/README.md

@@ -18,9 +18,34 @@ require "sevgi/geometry"
 
 ```ruby
 rect = Sevgi::Geometry::Rect[3, 5]
-rect.box.width
+rect.center                    # => Point[1.5, 2.5]
+rect.closed?                   # => true
+rect.vertices.size             # => 4
+rect.points.size               # => 5
+rect.translate(2, 1).position # => Point[2.0, 1.0]
+
+Sevgi::Geometry::Point.midpoint([0, 0], [3, 5]) # => Point[1.5, 2.5]
+```
+
+Geometry uses SVG screen coordinates. Positive x goes right, positive y goes down, and positive angles turn clockwise.
+Operations return new immutable values.
+
+Open lined paths expose `starting`, `ending`, and `reverse`. Use `closed?` to distinguish open and closed boundaries.
+Closed lined paths repeat their first vertex at the end of `points`. `vertices` omits that path-closing repetition.
+
+`Ellipse` and `Circle` describe closed boundaries. `Arc` selects a finite, directed part of an ellipse:
+
+```ruby
+ellipse = Sevgi::Geometry::Ellipse[40, 20, position: [50, 30]]
+arc = ellipse.arc starting_angle: 180, extent: 120
+arc.box
+arc.length
+arc.intersection Sevgi::Geometry::Equation.vertical(50)
 ```
 
+Positive extent turns clockwise. Its absolute value must be less than 360 degrees.
+Bounds and length do not depend on display precision. Closed ellipses and circles also support line sweeps.
+
 ## Ruby compatibility
 
 Requires Ruby 3.4.0 or newer. CI verifies the current Ruby 3.4 release and the development Ruby from `.ruby-version`.

data/lib/sevgi/geometry/element.rb

@@ -12,7 +12,7 @@ module Sevgi
 
       # @overload lined(size = Undefined, open: false)
       #   Builds a lined element subclass.
-      #   Instances expose total path `length`; closed classes additionally expose `perimeter`.
+      #   Instances expose total path `length`. Closed classes also expose `perimeter`.
       #   @param size [Integer, Sevgi::Undefined] segment count for fixed-size elements, or Undefined for variable size
       #   @param open [Boolean] true for an open path, false for a closed path
       #   @return [Class] subclass of {Sevgi::Geometry::Element::Lined}
@@ -22,16 +22,6 @@ module Sevgi
       #   Path.([0, 0], [1, 0], [1, 1])
       def self.lined(...) = Lined.send(:build, ...)
 
-      # @overload arced(*args)
-      #   Builds an arced element subclass.
-      #   @api private
-      #   @param args [Array<Object>] arced factory arguments
-      #   @return [Class]
-      #   @raise [NoMethodError] until arced elements are implemented
-      def self.arced(...) = Arced.build(...)
-
-      private_class_method :arced
-
       # Core API
 
       # Returns a copy moved to a point and optional offset.
@@ -62,7 +52,12 @@ module Sevgi
       # @raise [Sevgi::PanicError] when a subclass does not implement box
       def box = PanicError.("#{self.class}#box must be implemented")
 
-      # Returns equations that define the element boundary.
+      # Reports whether the element boundary forms a closed path.
+      # @return [Boolean]
+      def closed? = self.class.send(:close?)
+
+      # Returns carrier equations for candidate boundary intersections.
+      # A finite element can represent only part of each carrier.
       # @abstract Subclasses implement element-specific equations.
       # @return [Array<Sevgi::Geometry::Equation>]
       # @raise [Sevgi::PanicError] when a subclass does not implement equations
@@ -73,6 +68,29 @@ module Sevgi
       # @return [Boolean]
       def ignorable?(precision: nil) = F.zero?(box.width, precision:) && F.zero?(box.height, precision:)
 
+      # Intersects the element boundary with an equation.
+      #
+      # Precision controls boundary membership, returned-coordinate rounding, and duplicate collapse.
+      # A nil precision uses the current thread's function precision for all three stages.
+      # @example Intersect a rectangle with a vertical line
+      #   rect = Sevgi::Geometry::Rect[8, 4]
+      #   axis = Sevgi::Geometry::Equation.vertical(3)
+      #   rect.intersection(axis).map(&:deconstruct) # => [[3.0, 0.0], [3.0, 4.0]]
+      # @param equation [Sevgi::Geometry::Equation] equation to intersect with
+      # @param precision [Integer, nil] coordinate precision, or nil for the current function default
+      # @return [Array<Sevgi::Geometry::Point>] unique boundary intersection points
+      # @raise [Sevgi::Geometry::Error] when equation is not an equation
+      # @raise [Sevgi::PanicError] when the equation combination is not implemented
+      def intersection(equation, precision: nil)
+        Error.("Must be an equation: #{equation}") unless equation.is_a?(Equation)
+
+        points = equations.flat_map do |candidate|
+          equation.intersect(candidate).select { |point| boundary_point?(point, precision) }
+        end
+
+        points.map { |point| point.approx(precision) }.uniq
+      end
+
       # Returns the element position.
       # @abstract Subclasses implement element-specific positioning.
       # @return [Sevgi::Geometry::Point]
@@ -87,14 +105,24 @@ module Sevgi
       # @raise [Sevgi::PanicError] when a subclass does not implement translate
       def translate(_x, _y) = PanicError.("#{self.class}#translate must be implemented")
 
+      def boundary_point?(point, precision)
+        return on?(point) if precision.nil?
+
+        F.with_precision(precision) { on?(point) }
+      end
+
+      private :boundary_point?
+
       # Element whose boundary is represented by straight segments.
       #
       # The same path is available as immutable {#points}, {#segments}, and
-      # {#lines} collections. Closed shapes repeat their first point at the end;
-      # open paths do not. Only closed shapes have a filled interior, so
-      # `inside?` on an open path is equivalent to testing its boundary.
-      # @example Inspect the interchangeable point, segment, and line views
+      # {#lines} collections. {#vertices} omits the repeated closing point from
+      # closed shapes. Open paths have the same values in `vertices` and `points`.
+      # Only closed shapes have a filled interior, so `inside?` on an open path
+      # is equivalent to testing its boundary.
+      # @example Inspect path and geometric views
       #   rect = Sevgi::Geometry::Rect[8, 4]
+      #   rect.vertices.size # => 4
       #   rect.points.size   # => 5
       #   rect.segments.size # => 4
       #   rect.lines.size    # => 4
@@ -103,6 +131,18 @@ module Sevgi
         # Open lined element base class.
         # @api private
         Open = Class.new(self) do
+          # Returns the first point in the directed path.
+          # @return [Sevgi::Geometry::Point]
+          def starting = points.first
+
+          # Returns the last point in the directed path.
+          # @return [Sevgi::Geometry::Point]
+          def ending = points.last
+
+          # Returns the same trace with opposite traversal.
+          # @return [Sevgi::Geometry::Element::Lined]
+          def reverse = self.class.send(:new_by_points!, *points.reverse)
+
           # Draws the element as an SVG polyline.
           # @param node [Object] graphics node receiving the drawing command
           # @return [Object] graphics node command result
@@ -313,13 +353,23 @@ module Sevgi
           approx.send(:draw!, ...)
         end
 
-        # Returns immutable element points.
+        # Returns immutable element points in path order.
+        # Closed elements repeat the first vertex at the end.
         # @param approximate [Boolean] true to round points with the current function precision
         # @return [Array<Sevgi::Geometry::Point>] frozen point collection
         def points(approximate = false)
           approximate ? rounded_points(nil) : @points
         end
 
+        # Returns immutable geometric vertices in path order.
+        # Closed elements omit the repeated closing point. Open elements return {#points}.
+        # @return [Array<Sevgi::Geometry::Point>] frozen vertex collection
+        def vertices
+          return points unless closed?
+
+          @vertices ||= points[...-1].freeze
+        end
+
         # Returns the first point.
         # @return [Sevgi::Geometry::Point]
         def position
@@ -420,29 +470,6 @@ module Sevgi
         # @return [Array<Sevgi::Geometry::Equation::Linear>] frozen equation collection
         def equations = @equations ||= lines.map(&:equation).freeze
 
-        # Intersects the element boundary with an equation.
-        #
-        # Precision is applied consistently to boundary-membership tolerance, returned-coordinate rounding, and
-        # duplicate collapse. A nil precision uses the current thread's function precision for all three stages.
-        # @example Intersect a rectangle with a vertical line
-        #   rect = Sevgi::Geometry::Rect[8, 4]
-        #   axis = Sevgi::Geometry::Equation.vertical(3)
-        #   rect.intersection(axis).map(&:deconstruct) # => [[3.0, 0.0], [3.0, 4.0]]
-        # @param equation [Sevgi::Geometry::Equation] equation to intersect with
-        # @param precision [Integer, nil] decimal precision for returned points, or nil for the current function default
-        # @return [Array<Sevgi::Geometry::Point>] unique boundary intersection points
-        # @raise [Sevgi::Geometry::Error] when equation is not an equation
-        # @raise [Sevgi::PanicError] when the equation combination is not implemented
-        def intersection(equation, precision: nil)
-          Error.("Must be an equation: #{equation}") unless equation.is_a?(Equation)
-
-          points = equations.flat_map do |candidate|
-            equation.intersect(candidate).select { |point| boundary_point?(point, precision) }
-          end
-
-          points.map { |point| point.approx(precision) }.uniq
-        end
-
         # Properties
 
         # Returns a line by index.
@@ -465,14 +492,19 @@ module Sevgi
         # @return [Sevgi::Geometry::Segment]
         def head = @head ||= segments.first
 
-        # Returns immutable boundary lines derived from segments and points.
+        # Returns immutable boundary lines with the stored endpoints and segments.
         # @return [Array<Sevgi::Geometry::Line>] frozen line collection
         def lines
-          @lines ||= segments
-            .zip(points[...segments.size])
-            .map { |segment, position|
-              segment.line(position)
-            }
+          @lines ||= points
+            .each_cons(2)
+            .zip(segments)
+            .map do |points, segment|
+              # Rebuilding from either view alone loses stored endpoints or input angles.
+              Line.send(:new) do
+                @points = points
+                @segments = [segment]
+              end
+            end
             .freeze
         end
 
@@ -488,7 +520,7 @@ module Sevgi
 
         # Reports whether a point is inside or on the boundary.
         #
-        # Open paths have no filled interior; for them this predicate is true
+        # Open paths have no filled interior. For them this predicate is true
         # only for points on the actual path boundary.
         # @example Compare closed and open path containment
         #   rect = Sevgi::Geometry::Rect[8, 4]
@@ -502,7 +534,7 @@ module Sevgi
         def inside?(point)
           point = Tuple[Point, point]
 
-          return on?(point) unless self.class.send(:close?)
+          return on?(point) unless closed?
 
           on?(point) || pnpoly(points, point)
         end
@@ -525,18 +557,11 @@ module Sevgi
 
         private
 
-        def boundary_point?(point, precision)
-          return on?(point) if precision.nil?
-
-          F.with_precision(precision) { on?(point) }
-        end
-
         def calculate_points_from_segments
           Error.("No segments found") unless segments
 
           [point = position, *segments.map { point = it.ending(point) }].tap do |points|
-            # Share the first point object when the path closes within the current precision.
-            points[-1] = points.first if points.first.eq?(points.last)
+            points[-1] = points.first if closed? && points.first.eq?(points.last)
           end
         end
 
@@ -578,7 +603,7 @@ module Sevgi
 
         def rounded_points(precision)
           rounded = @points.map { it.approx(precision) }
-          rounded[-1] = rounded.first if self.class.send(:close?)
+          rounded[-1] = rounded.first if closed?
           rounded.freeze
         end
 
@@ -592,7 +617,7 @@ module Sevgi
 
           Error.("Wrong number of points;  expected #{np} where found #{points.size}") unless points.size == np
           Error.("Wrong number of segments; expected #{ns} where found #{segments.size}") unless segments.size == ns
-          return unless self.class.send(:close?) && !points.first.eq?(points.last)
+          return unless closed? && !points.first.eq?(points.last)
 
           Error.("Element points must form a closed path")
         end
@@ -600,12 +625,38 @@ module Sevgi
         def validate_geometry! = nil
       end
 
-      # Reserved base for future arced elements.
-      # @api private
+      # Abstract family of circular and elliptical boundary elements.
+      # Arc is open, while Ellipse and Circle have closed boundaries. Concrete values share exact and precision-aware comparisons.
       class Arced < self
+        # Compares canonical fields with coordinate and numeric precision.
+        # @param other [Object] comparison target
+        # @param precision [Integer, nil] decimal precision, or nil for the current function default
+        # @return [Boolean]
+        def eq?(other, precision: nil)
+          other.instance_of?(self.class) &&
+            state.zip(other.send(:state)).all? do |left, right|
+              left.is_a?(::Numeric) ? F.eq?(left, right, precision:) : left.eq?(right, precision:)
+            end
+        end
+
+        # Reports strict equality by concrete class and canonical fields.
+        # @param other [Object] comparison target
+        # @return [Boolean]
+        def eql?(other) = other.instance_of?(self.class) && state == other.send(:state)
+
+        # Returns a hash independent of numeric precision.
+        # @return [Integer]
+        def hash = [self.class, *state].hash
+
+        # Reports whether a point is outside the element.
+        # @param point [Sevgi::Geometry::Point, Array<Numeric>] point to test
+        # @return [Boolean]
+        # @raise [Sevgi::Geometry::Error] when point cannot be coerced
+        def outside?(point) = !inside?(point)
+
+        alias == eql?
       end
 
-      private_constant :Arced
     end
 
     require_relative "elements/line"
@@ -614,5 +665,8 @@ module Sevgi
     require_relative "elements/polyline"
     require_relative "elements/rect"
     require_relative "elements/triangle"
+    require_relative "elements/ellipse"
+    require_relative "elements/circle"
+    require_relative "elements/arc"
   end
 end