sevgi-graphics 0.98.2 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 753194f4865e2c8b099f788588a684a72a116004b3e56bb40cfd626a7b14043f
-  data.tar.gz: d443e433a8c86e4d902b31a4dadb71a244905f83aca4b67d8d56c64fdd7cb6c7
+  metadata.gz: 7965ed7aa4c5960cca6a4ed927258d13a5b5be7d9e327f4bf7da5b3480b66b1f
+  data.tar.gz: 88224f9179c50ceca0ae8e4ee7a92e5d8a6a0d2634ec3912356dc5e5d2d27053
 SHA512:
-  metadata.gz: 05517e6f426cc1cd7ce0077705f147db602346bfba518500551dfce4008d669935f1fe3f21fc83b4531f33a44e4eec38e5b3ff82ccceff1bf1968a30f7ce8998
-  data.tar.gz: d19ec2a6d3e5e093876ab72eaa594220241f5ff8f5c744124330ee69adff71f12a67159779b9894a6bd4589ea0b3af78ad16ed768d41b422ffc18bca77248075
+  metadata.gz: 063d2529fc5869ef25f27ed44b927d28ae3ba6c48aca2365c0be78dbda65b895eb065b0c61ca960e66f955e0a8dbea8cc7b581ddf9ad4ec437c727e0541b9e43
+  data.tar.gz: fa1a68f7962e62bd991462e87bbbae0778321076af509ca2ede6b179a5eb1c133d707c3450d46688645ddf37050df49c63df608236fc1cfb3bcc811d20ff25a5

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,12 @@ require "sevgi/graphics"
 
 ```ruby
 doc = Sevgi::Graphics.SVG(:minimal) { rect width: 3, height: 5 }
-doc.call
+puts doc.Render
 ```
 
+This focused gem exposes `Sevgi::Graphics.SVG` and lowercase component constructors. Install the umbrella `sevgi` gem
+when you need the global `SVG` facade or the `.sevgi` script runner.
+
 ## 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/graphics/attribute.rb

@@ -60,6 +60,9 @@ module Sevgi
       # Owned mutable snapshots for values entering an attribute store.
       # @api private
       module Snapshot
+        SCALARS = [::NilClass, ::TrueClass, ::FalseClass, ::Symbol, ::Integer, ::Float, ::Rational, ::Complex].freeze
+        private_constant :SCALARS
+
         class << self
           def capture(value, normalize_keys: false, seen: {}.compare_by_identity)
             case value
@@ -90,12 +93,7 @@ module Sevgi
 
           def capture_value(value)
             text = XML.text(value, context: "XML attribute value")
-            case value
-            when ::Numeric, ::Symbol, ::NilClass, ::TrueClass, ::FalseClass
-              value
-            else
-              text
-            end
+            SCALARS.include?(value.class) ? value : text
           end
 
           def nested(value, seen)
@@ -172,7 +170,7 @@ module Sevgi
       # @api private
       class Store
         # Creates an attribute store from recursively owned snapshots. Mutable non-container leaves are stringified
-        # once; later caller mutation cannot change the store.
+        # once. Later caller mutation cannot change the store.
         # @param attributes [Hash] initial attributes
         # @return [void]
         # @raise [Sevgi::ArgumentError] when input is not a Hash or a name/value is invalid, cyclic, colliding, or cannot
@@ -205,7 +203,7 @@ module Sevgi
 
         # Assigns a recursively owned attribute snapshot. Mutable non-container leaves are stringified once.
         # @param key [String, Symbol] attribute key
-        # @param value [Object, nil] attribute value; nil is ignored
+        # @param value [Object, nil] attribute value. Nil is ignored
         # @return [Object, nil] stored snapshot or nil
         # @raise [Sevgi::ArgumentError] when update syntax receives incompatible values
         # @raise [Sevgi::ArgumentError] when update syntax receives an unsupported value type
@@ -354,7 +352,7 @@ module Sevgi
 
       # Assigns or updates a recursively owned attribute value.
       # @param key [String, Symbol] attribute key, optionally ending in {UPDATE_SUFFIX}
-      # @param value [Object, nil] attribute value; nil is ignored
+      # @param value [Object, nil] attribute value. Nil is ignored
       # @return [Object, nil] recursively owned resulting value or nil when absent
       # @raise [Sevgi::ArgumentError] when the name or value is invalid, or an existing update uses incompatible or
       #   unsupported value families
@@ -392,7 +390,7 @@ module Sevgi
       def keys = @store.list.freeze
 
       # Atomically assigns or updates recursively owned attributes.
-      # @param attributes [Hash] attributes and non-rendering metadata; names may end in {UPDATE_SUFFIX}
+      # @param attributes [Hash] attributes and non-rendering metadata. Names can end in {UPDATE_SUFFIX}
       # @return [Sevgi::Graphics::Attributes] self
       # @raise [Sevgi::ArgumentError] when input is not a Hash, names collide, a name or value is invalid, or an existing
       #   update uses incompatible or unsupported value families

data/lib/sevgi/graphics/auxiliary/canvas.rb

@@ -113,12 +113,12 @@ module Sevgi
 
       # @overload attributes(origin = Undefined)
       #   Returns SVG root viewport attributes.
-      #   Omission uses the negative left and top margins; nil uses zero for both coordinates.
+      #   Omission uses the negative left and top margins. Nil uses zero for both coordinates.
       #   @example Compare margin-aware and zero-origin viewBoxes
       #     canvas = Sevgi::Graphics::Canvas.call(width: 80, height: 50, margins: [5, 10])
       #     canvas.attributes[:viewBox] # => "-10 -5 80 50"
       #     canvas.attributes(nil)[:viewBox] # => "0 0 80 50"
-      #   @param origin [Numeric, Array<Numeric>, nil, Sevgi::Undefined] viewBox origin; a scalar sets both coordinates
+      #   @param origin [Numeric, Array<Numeric>, nil, Sevgi::Undefined] viewBox origin. A scalar sets both coordinates
       #   @return [Hash{Symbol => String}] SVG viewport and viewBox attributes
       #   @raise [Sevgi::ArgumentError] when origin is invalid
       def attributes(...) = {**viewport, viewBox: viewbox(...)}
@@ -142,8 +142,8 @@ module Sevgi
       def viewport = {width: "#{width}#{unit}", height: "#{height}#{unit}"}
 
       # Returns the SVG viewBox string.
-      # Omission uses the negative left and top margins; nil uses zero for both coordinates.
-      # @param origin [Numeric, Array<Numeric>, nil, Sevgi::Undefined] viewBox origin; a scalar sets both coordinates
+      # Omission uses the negative left and top margins. Nil uses zero for both coordinates.
+      # @param origin [Numeric, Array<Numeric>, nil, Sevgi::Undefined] viewBox origin. A scalar sets both coordinates
       # @return [String]
       # @raise [Sevgi::ArgumentError] when origin is invalid
       def viewbox(origin = Undefined) = prettify(*originate(origin), width, height).join(" ")

data/lib/sevgi/graphics/auxiliary/content.rb

@@ -30,7 +30,7 @@ module Sevgi
     #   Sevgi::Graphics.SVG(:minimal) { text Emphasis["important & safe"] }.Render
     #
     #   # The renderer ignores Emphasis#render's return value. Custom content must escape inserted data itself.
-    # @see https://sevgi.roktas.dev/svg/#content-safety Content safety guide
+    # @see https://sevgi.roktas.dev/documents/#content-safety Content safety guide
     class Content
       private_class_method :new
 
@@ -106,7 +106,7 @@ module Sevgi
       # @return [Object] wrapped content snapshot
       def content = Snapshot.copy(@content)
 
-      # Creates immutable content from a deep payload snapshot. Strings and containers are copied recursively; mutable
+      # Creates immutable content from a deep payload snapshot. Strings and containers are copied recursively. Mutable
       # non-container objects are stringified once during construction. The caller's objects are never retained.
       # @param content [Object] wrapped content
       # @return [void]
@@ -118,17 +118,6 @@ module Sevgi
         XML.validate(@content)
       end
 
-      # Copies content payload ownership for duplicated element trees.
-      # @param original [Sevgi::Graphics::Content] source content
-      # @return [void]
-      # @api private
-      def initialize_copy(original)
-        @content = Snapshot.capture(original.content)
-        super
-      end
-
-      private :initialize_copy
-
       # Appends this content's serialized XML lines to rendering output.
       # The output collaborator responds to `append(depth, *lines)`, where `depth` is an Integer or nil and every line
       # is a String containing valid serialized XML text. The rendering engine ignores both `append` and `render` return
@@ -185,7 +174,7 @@ module Sevgi
       def self.verbatim(...) = Verbatim.send(:new, ...)
 
       # CDATA section content backed by an immutable payload snapshot. Mutable leaf objects are stringified during
-      # construction; embedded terminators are split during rendering.
+      # construction. Embedded terminators are split during rendering.
       # @see Content.cdata
       class CData < Content
         # Renders CDATA content.
@@ -206,7 +195,7 @@ module Sevgi
         def safe(value) = XML.cdata(value)
       end
 
-      # CSS content rendered inside a CDATA section. Rules are captured recursively during construction; mutable
+      # CSS content rendered inside a CDATA section. Rules are captured recursively during construction. Mutable
       # selectors, property names, and values are stringified once, and embedded CDATA terminators are split safely.
       # @see Content.css
       class CSS < Content
@@ -281,7 +270,7 @@ module Sevgi
       end
 
       # Verbatim content backed by an immutable payload snapshot. Mutable leaf objects are stringified during
-      # construction. Verbatim content bypasses XML escaping; validation guarantees encoding and legal XML 1.0 code
+      # construction. Verbatim content bypasses XML escaping. Validation guarantees encoding and legal XML 1.0 code
       # points, not well-formed markup supplied by the caller.
       # @see Content.verbatim
       class Verbatim < Content

data/lib/sevgi/graphics/document/base.rb

@@ -4,8 +4,8 @@ module Sevgi
   module Graphics
     module Document
       # Abstract common document layer with the profile-independent DSL mixture set. It is not registered as a
-      # selectable profile. Advanced extensions may target this class through {Sevgi::Graphics::Mixtures.mixin}; doing
-      # so changes every descendant profile process-wide. Subclass it first when an extension should remain scoped.
+      # selectable profile. Advanced extensions can target this class through {Sevgi::Graphics::Mixtures.mixin}. This
+      # changes every descendant profile process-wide. Subclass it first to keep an extension scoped.
       class Base < Proto
         document nil, register: false
 

data/lib/sevgi/graphics/document.rb

@@ -5,7 +5,7 @@ module Sevgi
     # SVG document profile factory and process-global named-profile registry.
     #
     # A profile owns SVG root attributes and optional preamble lines, but not canvas size. Built-in and named profiles
-    # can be passed to {Sevgi::Graphics.SVG}; an anonymous profile class is useful when library code needs one-off
+    # can be passed to {Sevgi::Graphics.SVG}. An anonymous profile class is useful when library code needs one-off
     # metadata without adding a global name.
     #
     # | Profile | Preamble | Root metadata | Additional DSL |
@@ -13,20 +13,23 @@ module Sevgi
     # | `:minimal` | none | none | common document DSL |
     # | `:default` | XML declaration | SVG namespace | common document DSL |
     # | `:html` | none | SVG namespace | common document DSL |
-    # | `:inkscape` | XML declaration | SVG and editor namespaces; crisp edges | `Draw`, `Hatch`, and editor/RDF helpers |
+    # | `:inkscape` | XML declaration | SVG and editor namespaces with crisp edges | `Draw`, `Hatch`, and editor/RDF helpers |
     #
     # The Inkscape root adds Sevgi, Inkscape, and Sodipodi namespaces plus `shape-rendering="crispEdges"`. Every
-    # selectable profile has the same validation and lint lifecycle; `:minimal` changes serialization metadata, not
+    # selectable profile has the same validation and lint lifecycle. `:minimal` changes serialization metadata, not
     # checking policy. {Base} is the public common extension layer rather than a selectable profile. {Minimal} and
     # {Default} are sibling concrete profiles: Minimal contributes no metadata and is not the semantic base of the other
-    # profiles. Targeting Base through {Sevgi::Graphics::Mixtures.mixin} changes every descendant profile process-wide;
-    # subclass Base first when an extension should remain scoped.
+    # profiles. Targeting Base through {Sevgi::Graphics::Mixtures.mixin} changes every descendant profile process-wide.
+    # Subclass Base first to keep an extension scoped.
     #
-    # @see https://sevgi.roktas.dev/svg/#document-profiles Document profiles guide
+    # @see https://sevgi.roktas.dev/documents/#profiles Document profiles guide
     module Document
       # Defensive copy helper for profile metadata snapshots.
       # @api private
       module Snapshot
+        SCALARS = [::NilClass, ::TrueClass, ::FalseClass, ::Symbol, ::Integer, ::Float, ::Rational, ::Complex].freeze
+        private_constant :SCALARS
+
         class << self
           # Captures recursively immutable profile metadata. Mutable non-container values are stringified once.
           # @param value [Object] value to capture
@@ -81,19 +84,8 @@ module Sevgi
           end
 
           def capture_value(value)
-            case value
-            when ::String
-              XML.text(value, context: "Document profile metadata").freeze
-            when ::Numeric, ::Symbol, ::NilClass, ::TrueClass, ::FalseClass
-              XML.text(value, context: "Document profile metadata")
-              value
-            else
-              stringify(value).freeze
-            end
-          end
-
-          def stringify(value)
-            XML.text(value, context: "Document profile metadata")
+            text = XML.text(value, context: "Document profile metadata")
+            SCALARS.include?(value.class) ? value : text.freeze
           end
         end
       end
@@ -194,7 +186,7 @@ module Sevgi
       # A name without metadata performs lookup. A name plus either metadata
       # keyword defines or compatibly reuses a named profile. Omitting the name
       # creates an anonymous class and leaves the registry unchanged. Named
-      # profiles are process-global; use them for shared vocabulary rather than
+      # profiles are process-global. Use them for shared vocabulary rather than
       # per-call configuration.
       # Profile metadata is captured before class or thread-atomic registry mutation. Mutable non-container attribute
       # values are stringified once, attribute names and nested Hash keys are normalized, and nil attributes are omitted
@@ -221,7 +213,7 @@ module Sevgi
         overwrite!(overwrite)
         return anonymous(attributes:, preambles:) if name == Undefined
 
-        return lookup(name) if preambles == Undefined && attributes == Undefined
+        return fetch(name) if preambles == Undefined && attributes == Undefined
 
         name = Name.normalize!(name)
         current = reuse(name, attributes:, preambles:, overwrite:)
@@ -240,10 +232,6 @@ module Sevgi
           Class.new(Base) { document(Undefined, preambles:, attributes:, register: false) }
         end
 
-        def lookup(name)
-          fetch(name)
-        end
-
         def defaults(attributes:, preambles:)
           [attributes == Undefined ? {} : attributes, preambles == Undefined ? nil : preambles]
         end
@@ -324,7 +312,7 @@ module Sevgi
       private_constant :Registry
 
       # Immutable, read-only document profile metadata exposed by document classes. Process-global lookup and registration
-      # are thread-atomic. Metadata containers and strings are captured recursively; other mutable attribute values are
+      # are thread-atomic. Metadata containers and strings are captured recursively. Other mutable attribute values are
       # stringified once during construction. Attribute names and nested Hash keys are normalized to Symbols, nil values
       # are omitted, and update-suffix intent is retained for inheritance.
       # Returned attribute and preamble collections are caller-owned snapshots,
@@ -336,7 +324,7 @@ module Sevgi
 
         # Creates profile metadata.
         # @param name [Object, nil] profile name
-        # @param attributes [Hash, nil] default root attributes; nil means an empty Hash
+        # @param attributes [Hash, nil] default root attributes. Nil means an empty Hash
         # @param preambles [Array<String>, nil] preamble lines
         # @return [void]
         # @raise [Sevgi::ArgumentError] when name or metadata is invalid XML, cyclic, or cannot be stringified

data/lib/sevgi/graphics/element.rb

@@ -6,16 +6,18 @@ module Sevgi
     #
     # @!method self.valid?(name)
     #   Reports whether a candidate can dispatch as an SVG element name.
-    #   With Standard loaded, the name must be known; standalone Graphics accepts any valid XML name.
+    #   With Standard loaded, the name must be known. Standalone Graphics accepts any valid XML name.
     #   @param name [Object] candidate element name
     #   @return [Boolean]
     #
     # Dynamic SVG element methods accept text, content objects, and any number of attribute Hashes in one call. Hashes
-    # are applied from left to right; later values replace earlier values unless their names use the `+` update suffix.
+    # are applied from left to right. Later values replace earlier values unless their names use the `+` update suffix.
+    # Ordinary `dup` and `clone` create independent subtrees, preserve IDs, and detach non-root copies from their parent.
+    # Document copies remain roots. Use `Duplicate` for DSL-specific ID remapping and attachment.
     class Element
       # Builds an element node.
       # @param name [Symbol, String] SVG element name
-      # @param arguments [Array<Hash, String, Sevgi::Graphics::Content>] ordered content and attribute channels; every
+      # @param arguments [Array<Hash, String, Sevgi::Graphics::Content>] ordered content and attribute channels. Every
       #   Hash is applied through {Sevgi::Graphics::Attributes} from left to right
       # @param parent [Sevgi::Graphics::Element] parent element
       # @yield evaluates the drawing DSL in the new element
@@ -178,9 +180,25 @@ module Sevgi
         instance_exec(&block) if block
       end
 
+      # Copies owned storage and reconnects child copies without attaching to the source tree.
+      # @param original [Sevgi::Graphics::Element] source node
+      # @return [void]
+      # @api private
+      def initialize_copy(original)
+        super
+        @parent = Element.root?(original) ? RootParent : DetachedParent
+        @attributes = original.attributes.dup
+        @contents = original.contents.map(&:dup)
+        @children = original.children.map do |child|
+          child.dup.tap { it.instance_variable_set(:@parent, self) }
+        end
+      end
+
+      private :initialize_copy
+
       # Dispatches SVG element DSL calls and caches valid element methods.
       # @param name [Symbol] missing method name
-      # @param arguments [Array<Hash, String, Sevgi::Graphics::Content>] ordered content and attribute channels; later
+      # @param arguments [Array<Hash, String, Sevgi::Graphics::Content>] ordered content and attribute channels. Later
       #   Hashes replace or update attributes assigned by earlier Hashes
       # @yield evaluates the drawing DSL in the dispatched child element
       # @yieldreturn [Object] ignored block result
@@ -232,7 +250,7 @@ module Sevgi
 
         # Parses element DSL arguments.
         # @param name [Symbol] SVG element name
-        # @param args [Array<Object>] positional DSL arguments; Hashes are imported from left to right
+        # @param args [Array<Object>] positional DSL arguments. Hashes are imported from left to right
         # @return [Hash] parsed :attributes and :contents
         # @raise [Sevgi::ArgumentError] when an argument is not a Hash, String, or Content
         def parse(name, *args)
@@ -257,9 +275,6 @@ module Sevgi
 
       private_constant :Dispatch
 
-      protected
-
-      attr_writer :attributes, :children, :contents, :parent
     end
   end
 end

data/lib/sevgi/graphics/mixtures/call.rb

@@ -4,10 +4,10 @@ module Sevgi
   module Graphics
     # Callable drawing module support.
     # Extend a plain Ruby module with this API to make its public instance methods callable drawing steps. Name the
-    # method `call` when the module has a single drawing step; use descriptive method names when it has multiple steps.
+    # method `call` when the module has a single drawing step. Use descriptive method names for multiple steps.
     # Base blocks add argument-independent shared SVG content once per invocation before the public drawing methods.
-    # Invocation does not change the configured module, so it may be frozen after its drawing steps are defined. A
-    # duplicate or clone owns an independent configuration snapshot; freezing a callable module prevents later base
+    # Invocation does not change the configured module, so it can be frozen after its drawing steps are defined. A
+    # duplicate or clone owns an independent configuration snapshot. Freezing a callable module prevents later base
     # registration while leaving invocation available.
     # @example Define and call a drawing module
     #   Widget = Module.new do
@@ -73,8 +73,9 @@ module Sevgi
 
       # Registers argument-independent shared drawing steps. Every invocation runs inherited base blocks parent-first,
       # then locally registered base blocks in registration order, before the module's public drawing methods. The block
-      # runs once in the current element context and does not receive the invocation arguments.
-      # @yield evaluates the drawing DSL in the current element context
+      # runs once on the callable receiver, which delegates drawing words to the current SVG element. It receives no
+      # invocation arguments. Callable methods receive those arguments and the caller's block unchanged.
+      # @yield evaluates shared drawing steps on the callable receiver
       # @yieldreturn [Object] ignored block result
       # @return [nil]
       # @raise [Sevgi::ArgumentError] when no block is given
@@ -133,7 +134,7 @@ module Sevgi
           invoke(context, receiver, methods, ...)
         end
 
-        # Returns the methods that should be executed for a callable module.
+        # Returns the executable drawing methods for a callable module.
         # @param mod [Module] module extended with {Sevgi::Graphics::Module}
         # @return [Array<UnboundMethod>]
         # @raise [Sevgi::ArgumentError] when mod is not a callable drawing module
@@ -173,26 +174,12 @@ module Sevgi
 
       private
 
-      # Gives a duplicated callable module independent configuration containers.
+      # Gives a copied callable module independent configuration containers.
       # @param original [Module] source callable module
       # @return [void]
       # @api private
-      def initialize_dup(original)
+      def initialize_copy(original)
         super
-        copy_configuration(original)
-      end
-
-      # Gives a cloned callable module independent configuration containers.
-      # @param original [Module] source callable module
-      # @param freeze [Boolean] whether Ruby preserves the source frozen state
-      # @return [void]
-      # @api private
-      def initialize_clone(original, freeze: true)
-        super
-        copy_configuration(original)
-      end
-
-      def copy_configuration(original)
         @sevgi_bases = original.instance_variable_get(:@sevgi_bases).dup
         @sevgi_callables = original.instance_variable_get(:@sevgi_callables).dup
         @sevgi_configuration_owner = object_id
@@ -216,8 +203,6 @@ module Sevgi
         own_configuration
         @sevgi_callables << method
       end
-
-      private :copy_configuration, :own_configuration
     end
 
     # Recursive callable drawing module support. Extend a module with this API when it and the modules defined beneath

data/lib/sevgi/graphics/mixtures/core.rb

@@ -94,7 +94,7 @@ module Sevgi
         end
 
         # Adds CSS classes without duplicating existing values.
-        # @param classes [Array<String, Symbol, Array>] class tokens; strings are split on whitespace
+        # @param classes [Array<String, Symbol, Array>] class tokens. Strings are split on whitespace
         # @return [Sevgi::Graphics::Element] self
         def Classify(*classes)
           tap do
@@ -128,7 +128,7 @@ module Sevgi
 
         # Builds a child element with an explicit tag name.
         # @param tag [Symbol, String] SVG tag name
-        # @param contents [Array<Object>] text or content objects; non-content objects are stringified and XML-encoded
+        # @param contents [Array<Object>] text or content objects. Non-content objects are stringified and XML-encoded
         # @param attributes [Hash] SVG attributes
         # @yield evaluates the drawing DSL in the new child element
         # @yieldreturn [Object] ignored block result
@@ -176,7 +176,7 @@ module Sevgi
         end
 
         # Returns the topmost element in this tree.
-        # A detached subtree returns its detached topmost element; use {#Root?} to distinguish a document root.
+        # A detached subtree returns its detached topmost element. Use {#Root?} to distinguish a document root.
         # @return [Sevgi::Graphics::Element] document root or detached topmost element
         def Root
           element = self
@@ -283,7 +283,7 @@ module Sevgi
         # Appends an element as a child.
         # @param element [Sevgi::Graphics::Element] element to append
         # @return [Sevgi::Graphics::Element] self
-        # @raise [Sevgi::ArgumentError] when the element has a different concrete class or would create a tree cycle
+        # @raise [Sevgi::ArgumentError] when the element has a different concrete class or creates a tree cycle
         def <<(element)
           Append(element)
         end
@@ -296,7 +296,7 @@ module Sevgi
           # @param parent [Sevgi::Graphics::Element] target parent
           # @param front [Boolean] whether to prepend instead of append
           # @return [void]
-          # @raise [Sevgi::ArgumentError] when an argument is incompatible, repeated, or would create a cycle
+          # @raise [Sevgi::ArgumentError] when an argument is incompatible, repeated, or creates a cycle
           def self.batch(elements, parent, front:)
             validate_batch(elements, parent)
 
@@ -307,11 +307,11 @@ module Sevgi
             end
           end
 
-          # Rejects target parents that would create a cycle.
+          # Rejects target parents that create a cycle.
           # @param element [Sevgi::Graphics::Element] element being moved
           # @param parent [Sevgi::Graphics::Element, Object] target parent
           # @return [void]
-          # @raise [Sevgi::ArgumentError] when the parent is incompatible or would create a cycle
+          # @raise [Sevgi::ArgumentError] when the parent is incompatible or creates a cycle
           def self.validate(element, parent)
             unless element.instance_of?(parent.class)
               ArgumentError.("Element type does not match the new parent type: #{element.class}")
@@ -347,8 +347,9 @@ module Sevgi
           # @param index [Integer] requested insertion index
           # @return [Integer] normalized insertion index
           def self.index_for(element, parent, index)
-            same_parent = element.parent.equal?(parent) && parent.children.include?(element)
-            index(index, parent.children.size - (same_parent ? 1 : 0))
+            children = Element.send(:tree_children, parent)
+            same_parent = element.parent.equal?(parent) && children.include?(element)
+            index(index, children.size - (same_parent ? 1 : 0))
           end
 
           def self.validate_batch(elements, parent)