sevgi-derender 0.98.2 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9d9e616e1b10140f4e9477ca8cc23f7912d56a6169b4e686a74353c816fe9706
-  data.tar.gz: e32b3958b5270380a74f218d87377a6fca87db2cfd3c518cd28530fcb7f97746
+  metadata.gz: e02ddd4869fac0f3ab35c12f53bcdd9e23bdc936d8753a17ff56b651c8a07882
+  data.tar.gz: aeff138c2ced508eca978c9eccd2e547c808e2be7d4d7bac859a57700e118892
 SHA512:
-  metadata.gz: '058bc5a453580bc9c32fd86a1d6a64474868c18b1ffe0af32ceb40d52a60263cfa1a787e1fac9f521ef31817f8a81991ddb65a33503a8b24e3743996f2dcd468'
-  data.tar.gz: eb906f2cb811fbbe73abeec77b298f68ee3db1de17366996762f02f4e36c0e5d392139cf83b4bc686d7fd7a156838065313fe1e7110d918dc3b45fe2a081fc85
+  metadata.gz: dee05c8a84e8872ce946aa18f3f10071c0b07bea43170cc3a59f03ef9b434383e184478c84fe43270bf9524af3b135ee827bbe55868a64b62099af8dc34f37a1
+  data.tar.gz: db4b7b23ca99f153f40ff0ec6bc2cdd126c399a466b93c3d92f028669a672de39e9dc783f093f1bb68fa1b738b7809fc6693651c19e251700248e9601afdb581

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,12 +18,25 @@ require "sevgi/derender"
 
 ```ruby
 source = "<svg><rect width=\"3\" height=\"5\"/></svg>"
-Sevgi::Derender.derender(source)
+puts Sevgi::Derender.derender(source)
+# SVG do
+#   rect width: 3, height: 5
+# end
 
 source = '<svg><rect id="mark" style="fill: red" width="3"/></svg>'
-Sevgi::Derender.derender(source, omit: %i[id style])
+puts Sevgi::Derender.derender(source, omit: %i[id style])
+# SVG do
+#   rect width: 3
+# end
 ```
 
+Use `decompile` to inspect an immutable parsed node. Use `evaluate` to add a selected node directly to an existing
+Sevgi document. Generated source is ordinary Ruby. Review it and integrate it statically instead of evaluating it
+dynamically.
+
+Derender reads the XML encoding declaration or byte-order mark. Generated Ruby and rendered XML use UTF-8.
+The XML declaration keeps its version and standalone flag, with any encoding field changed to UTF-8.
+
 ## Executable
 
 ```sh
@@ -49,7 +62,7 @@ Requires Ruby 3.4.0 or newer. CI verifies the current Ruby 3.4 release and the d
 
 ## Native prerequisites
 
-This gem needs no native libraries of its own. Nokogiri may use platform packages depending on the target Ruby platform.
+This gem needs no native libraries of its own. Nokogiri can use platform packages on some Ruby platforms.
 
 ## Links
 

data/lib/sevgi/binaries/igves.rb

@@ -88,10 +88,10 @@ module Sevgi
       rescue ::StandardError => e
         raise if raw_error?(options)
 
-        die(e, nil)
+        die(e)
       end
 
-      def die(error, _file)
+      def die(error)
         warn(error.message)
         warn("")
         backtrace(error).each { warn("  #{it}") }
@@ -142,7 +142,7 @@ module Sevgi
       rescue ::StandardError => e
         raise if raw_error?(options)
 
-        die(e, file)
+        die(e)
       end
 
       def raw_error?(options)

data/lib/sevgi/derender/attributes.rb

@@ -35,7 +35,6 @@ module Sevgi
 
         {**pre, **hash, **post}
           .map do |key, value|
-            key = Css.to_key(key) if key.is_a?(::String)
 
             if key == "style"
               style = Css.declarations(value)

data/lib/sevgi/derender/document.rb

@@ -20,7 +20,7 @@ module Sevgi
 
         ArgumentError.("File not found: #{path}") unless ::File.exist?(entry)
 
-        content = ::File.read(entry)
+        content = ::File.binread(entry)
         new(content)
       end
 
@@ -30,7 +30,7 @@ module Sevgi
       # @raise [Sevgi::ArgumentError] when content is not well-formed XML
       # @raise [Sevgi::ArgumentError] when content has no root element
       def self.parse(content)
-        Nokogiri::XML(content.to_s.lstrip, &:strict).tap do |doc|
+        Nokogiri::XML(content.to_s.b.sub(/\A[ \t\r\n]+/, ""), &:strict).tap do |doc|
           ArgumentError.("XML document has no root element") unless doc.root
         end
 
@@ -38,20 +38,26 @@ module Sevgi
         raise ArgumentError, "Malformed XML: #{e.message.lines.first.strip}", cause: e
       end
 
-      # Extracts the XML declaration from SVG/XML content.
+      # Extracts the XML declaration and aligns its encoding with UTF-8 output.
       # @param content [String] SVG/XML source content
+      # @param encoding [String, nil] source encoding reported by the XML parser
       # @return [String, nil] XML declaration line, if present
-      def self.declaration(content)
-        return unless (content = content.to_s.lstrip).start_with?("<?xml ")
-
-        content[/\A<\?xml\b.*?\?>/m]
+      def self.declaration(content, encoding: nil)
+        content = content.to_s.b
+        encoding ||= content.start_with?("\xFF\xFE".b, "\xFE\xFF".b) ? "UTF-16" : "UTF-8"
+        content = content.encode("UTF-8", encoding).delete_prefix("\uFEFF").lstrip
+        declaration = content[/\A<\?xml[ \t\r\n].*?\?>/m]
+
+        declaration&.sub(/encoding\s*=\s*(["']).*?\1/, "encoding=\"UTF-8\"")
+      rescue EncodingError, ::ArgumentError => e
+        raise ArgumentError, "Invalid XML encoding: #{e.message}", cause: e
       end
 
       # Returns the parsed XML document.
       # @return [Nokogiri::XML::Document]
       attr_reader :doc
 
-      # Returns the source XML declaration when present.
+      # Returns the XML declaration with its encoding field normalized to UTF-8, when present.
       # @return [String, nil]
       attr_reader :decl
 
@@ -62,7 +68,8 @@ module Sevgi
       # @raise [Sevgi::ArgumentError] when content has no root element
       def initialize(content)
         @doc = self.class.parse(content)
-        @decl = self.class.declaration(content)
+        @decl = self.class.declaration(content, encoding: doc.encoding)
+        @doc.encoding = "UTF-8"
       end
 
       # Converts the root or selected node into a derender node.
@@ -72,22 +79,19 @@ module Sevgi
       # @raise [Sevgi::ArgumentError] when the document has no root element or the id is absent
       def decompile(id = nil, omit: nil)
         if id
-          if (found = doc.xpath("//*[@id=#{xpath_literal(id)}]") || []).empty?
-            ArgumentError.("No such element with id '#{id}' in document")
-          end
-
-          found.first
+          doc.at_xpath("//*[@id=#{xpath_literal(id)}]") || ArgumentError.("No such element with id '#{id}' in document")
         else
           doc.root
         end => element
 
         ArgumentError.("XML document has no root element") unless element
+        validate_selection(element, whole: !id)
 
         Node.send(:new, element, pres, namespaces: namespace_scope(element), omit: omissions(omit))
       end
 
-      # Returns XML declaration and pre-root nodes preserved for root decompilation. The result contains only String
-      # lines and omits the declaration when the source did not provide one.
+      # Returns the XML declaration and pre-root nodes as UTF-8 for root decompilation.
+      # The result omits the declaration when the source did not provide one.
       # @return [Array<String>] preamble XML lines
       def pres
         @pres ||= [].tap do |lines|
@@ -99,6 +103,19 @@ module Sevgi
 
       private
 
+      def validate_selection(element, whole:)
+        if whole && doc.root.next_sibling
+          ArgumentError.("XML nodes after the root element are not supported")
+        end
+
+        element.traverse do |node|
+          references = [node, *node.attribute_nodes.flat_map { it.children.to_a }]
+          if references.any? { it.type == Nokogiri::XML::Node::ENTITY_REF_NODE }
+            ArgumentError.("Custom XML entity references are not supported")
+          end
+        end
+      end
+
       def namespace_scope(element)
         element == doc.root ? local_namespaces(element) : element.namespaces
       end

data/lib/sevgi/derender/elements/any.rb

@@ -8,21 +8,19 @@ module Sevgi
       module Any
         # Converts this node into unformatted Sevgi DSL lines.
         # @return [Array<String>] unformatted Ruby source lines
-        def decompile(*)
+        def decompile(*, namespaces: self.namespaces())
           if children.any?
-            children.one? && children.first.send(:text?) ? Array(leaf(has_attributes: attributes.any?)) : tree
+            text_leaf? ? Array(leaf(Ruby.literal(content), namespaces:)) : tree(namespaces)
           else
-            Array(leaf(has_content: false))
+            Array(leaf(namespaces:))
           end
         end
 
         private
 
-        def leaf(has_content: true, has_attributes: true)
-          attributes = all_attributes
-          args = []
-          args << Ruby.literal(content) if has_content
-          args << Attributes.decompile(attributes) if has_attributes && attributes.any?
+        def leaf(*args, namespaces:)
+          attributes = all_attributes(namespaces)
+          args << Attributes.decompile(attributes) if attributes.any?
 
           return explicit_leaf(args) unless bare?
 
@@ -37,9 +35,11 @@ module Sevgi
           args.empty? ? "#{call})" : "#{call}, #{args.join(", ")})"
         end
 
-        def tree
+        def tree(namespaces)
+          opening = inline_content? ? leaf(Ruby.literal(""), namespaces:) : leaf(namespaces:)
+
           [
-            "#{leaf(has_content: false)} do",
+            "#{opening} do",
             *children.map { it.send(:decompile) }.flatten,
             "end"
           ]

data/lib/sevgi/derender/elements/comment.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Sevgi
+  module Derender
+    module Elements
+      # Element strategy for XML comments.
+      # @api private
+      module Comment
+        # Converts a comment into a floating DSL node.
+        # @return [Array<String>] unformatted Ruby source lines
+        def decompile(*)
+          markup = "<!--#{content}-->"
+          ["_ Sevgi::Graphics::Content.verbatim(#{Ruby.literal(markup)})"]
+        end
+      end
+    end
+  end
+end

data/lib/sevgi/derender/elements/css.rb

@@ -8,21 +8,21 @@ module Sevgi
       module CSS
         # Converts a style node into unformatted Sevgi DSL lines.
         # @return [Array<String>] unformatted Ruby source lines
-        def decompile(*)
-          return raw_style unless (lines = css_lines)
+        def decompile(*, namespaces: self.namespaces())
+          return raw_style(namespaces) unless (lines = css_lines)
 
           [
             "css({",
             *lines,
-            "}, #{css_attributes})",
+            "}, #{css_attributes(namespaces)})",
             ""
           ]
         end
 
         private
 
-        def css_attributes
-          attributes = all_attributes
+        def css_attributes(namespaces)
+          attributes = all_attributes(namespaces)
           source = Attributes.decompile(attributes)
 
           attributes.key?("type") ? source : [source, "type: nil"].reject(&:empty?).join(", ")
@@ -42,9 +42,10 @@ module Sevgi
             .flatten
         end
 
-        def raw_style
+        def raw_style(namespaces)
           arguments = ["Sevgi::Graphics::Content.cdata(#{Ruby.literal(node.content)})"]
-          arguments << Attributes.decompile(all_attributes) if all_attributes.any?
+          attributes = all_attributes(namespaces)
+          arguments << Attributes.decompile(attributes) if attributes.any?
 
           ["style #{arguments.join(", ")}", ""]
         end

data/lib/sevgi/derender/elements/instruction.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Sevgi
+  module Derender
+    module Elements
+      # Preserves XML processing instructions as inert markup.
+      # @api private
+      module Instruction
+        # Converts a processing instruction into a floating DSL node.
+        # @return [Array<String>] unformatted Ruby source lines
+        def decompile(*)
+          ["_ Sevgi::Graphics::Content.verbatim(#{Ruby.literal(content)})"]
+        end
+      end
+    end
+  end
+end

data/lib/sevgi/derender/elements/root.rb

@@ -11,20 +11,27 @@ module Sevgi
         # Converts the SVG root into unformatted Sevgi DSL lines.
         # @param pres [Array<String>] preamble XML lines
         # @return [Array<String>] unformatted Ruby source lines
-        def decompile(pres = [])
+        def decompile(pres = [], **)
           lines = super
           return lines unless pres&.any?
 
-          lines.unshift(
-            [
-              "SVG.Document preambles: [",
-              *pres.map { "#{Ruby.literal(it)}," },
-              "]",
-              ""
-            ]
-          )
+          lines[0] = document_call(lines.first)
+
+          lines.unshift(preamble_lines(pres))
+        end
+
+        def document_call(line)
+          return line.sub("SVG", "SVG document") if ["SVG", "SVG do"].include?(line)
+
+          line.sub(/\ASVG /, "SVG document, ")
         end
 
+        def preamble_lines(pres)
+          ["document = SVG.Document preambles: [", *pres.map { "#{Ruby.literal(it)}," }, "]", ""]
+        end
+
+        private :document_call, :preamble_lines
+
         # Returns the root DSL word.
         # @return [String]
         def element = "SVG"

data/lib/sevgi/derender/elements/text.rb

@@ -10,6 +10,17 @@ module Sevgi
         # @return [Array<String>] unformatted Ruby source lines
         def decompile(*) = ["_ #{Ruby.literal(content)}"]
       end
+
+      # Element strategy for CDATA sections.
+      # @api private
+      module CData
+        # Converts CDATA into a floating content node.
+        # @return [Array<String>] unformatted Ruby source lines
+        def decompile(*)
+          markup = "<![CDATA[#{Graphics.const_get(:XML).cdata(content)}]]>"
+          ["_ Sevgi::Graphics::Content.verbatim(#{Ruby.literal(markup)})"]
+        end
+      end
     end
   end
 end

data/lib/sevgi/derender/elements.rb

@@ -10,7 +10,8 @@ module Sevgi
 end
 
 require_relative "elements/any"
+require_relative "elements/comment"
+require_relative "elements/instruction"
 require_relative "elements/css"
-require_relative "elements/junk"
 require_relative "elements/root"
 require_relative "elements/text"

data/lib/sevgi/derender/evaluator.rb

@@ -12,42 +12,48 @@ module Sevgi
 
       # Appends a derender node to the target parent.
       # @param node [Sevgi::Derender::Node] derender node
+      # @param namespaces [Hash{String => String}] namespace declarations for the appended node
       # @return [Sevgi::Graphics::Element, nil] included element, or nil when the node does not produce graphics output
-      def append(node)
-        case node.send(:type)
-        when :CSS
-          append_css(node)
-        when :Text
-          build(:_, node.content)
-        else
-          append_element(node)
-        end
+      def append(node, namespaces: node.namespaces)
+        type = node.send(:type)
+        return append_css(node, namespaces) if type == :CSS
+        return build(:_, node.content) if type == :Text
+        return append_cdata(node) if type == :CData
+        return build(:_, Graphics::Content.verbatim("<!--#{node.content}-->")) if type == :Comment
+        return build(:_, Graphics::Content.verbatim(node.content)) if type == :Instruction
+
+        append_element(node, namespaces)
       end
 
       private
 
       attr_reader :parent
 
-      def append_css(node)
+      def append_cdata(node)
+        body = Graphics.const_get(:XML).cdata(node.content)
+        build(:_, Graphics::Content.verbatim("<![CDATA[#{body}]]>"))
+      end
+
+      def append_css(node, namespaces)
         content = if (hash = Css.rules(node.content))
           Graphics::Content.css(hash)
         else
           Graphics::Content.cdata(node.content)
         end
 
-        build(:style, content, **node.send(:all_attributes))
+        build(:style, content, **node.send(:all_attributes, namespaces))
       end
 
-      def append_element(node)
+      def append_element(node, namespaces)
         contents = contents(node)
 
-        build(node.name, *contents, **attributes(node)).tap do |element|
-          node.children.each { self.class.new(element).append(it) } if contents.empty?
+        build(node.name, *contents, **attributes(node, namespaces)).tap do |element|
+          node.children.each { self.class.new(element).append(it) } unless node.send(:text_leaf?)
         end
       end
 
-      def attributes(node)
-        attributes = node.send(:all_attributes)
+      def attributes(node, namespaces)
+        attributes = node.send(:all_attributes, namespaces)
         return attributes unless (style = attributes["style"])
         return attributes unless (declarations = Css.declarations(style))
 
@@ -55,7 +61,9 @@ module Sevgi
       end
 
       def contents(node)
-        node.children.one? && node.children.first.send(:text?) ? [node.content] : []
+        return [node.content] if node.send(:text_leaf?)
+
+        node.send(:inline_content?) ? [""] : []
       end
 
       def build(name, *contents, **attributes)

data/lib/sevgi/derender/internal.rb

@@ -51,16 +51,11 @@ module Sevgi
         nil
       end
 
-      # Converts a CSS key into a Ruby hash key.
-      # @param arg [String] CSS key
-      # @return [String] Ruby hash key source
-      def to_key(arg) = arg
-
       # Converts a CSS key/value pair into Ruby hash source.
       # @param key [String] CSS declaration key
       # @param value [String] CSS declaration value
       # @return [String] Ruby hash pair source
-      def to_key_value(key, value) = "#{Ruby.literal(to_key(key))}: #{to_value(value)}"
+      def to_key_value(key, value) = "#{Ruby.literal(key)}: #{to_value(value)}"
 
       # Converts a CSS value into Ruby source.
       # @param arg [String] CSS value

data/lib/sevgi/derender/node.rb

@@ -25,11 +25,20 @@ module Sevgi
     # Captures owned Node state during construction.
     # @api private
     module Capture
+      NODE_TYPES = {
+        Nokogiri::XML::Node::TEXT_NODE => :Text,
+        Nokogiri::XML::Node::CDATA_SECTION_NODE => :CData,
+        Nokogiri::XML::Node::COMMENT_NODE => :Comment,
+        Nokogiri::XML::Node::PI_NODE => :Instruction
+      }.freeze
+      private_constant :NODE_TYPES
+
       private
 
       def capture_context(pres, namespaces)
         @pres = pres.map { it.to_s.dup.freeze }.freeze
         @namespaces = snapshot(namespaces || local_namespaces)
+        @scope = snapshot(node.namespaces)
         @type = dispatch
         singleton_class.send(:private, :decompile)
       end
@@ -53,10 +62,17 @@ module Sevgi
       end
 
       def capture_identity
-        @content = (preserve_space? ? node.content : normalized_content).dup.freeze
+        @content = captured_content.dup.freeze
+
         @name = [node.namespace&.prefix, node.name].compact.join(":").freeze
       end
 
+      def captured_content
+        return node.to_xml if node.processing_instruction?
+
+        literal_content? || preserve_space? ? node.content : normalized_content
+      end
+
       def metadata(key, value)
         [key.delete_prefix(META_NAMESPACE), value] if key.start_with?(META_NAMESPACE)
       end
@@ -74,7 +90,7 @@ module Sevgi
 
     # Immutable conversion result for one SVG/XML node.
     #
-    # Attributes, namespaces, content, and descendants are owned snapshots; parser objects and dispatch strategies
+    # Attributes, namespaces, content, and descendants are owned snapshots. Parser objects and dispatch strategies
     # remain internal to Derender. Attributes omitted during decompilation are absent throughout the captured subtree.
     class Node
       include Capture
@@ -90,7 +106,8 @@ module Sevgi
       attr_reader :children
 
       # Returns immutable normalized text content. `xml:space="preserve"` and single-line mixed text retain their exact
-      # text. Other text trims surrounding whitespace; multiline mixed text removes only its outer indentation lines.
+      # text. Other text trims surrounding whitespace. Multiline mixed text removes only its outer indentation lines.
+      # For a processing instruction, content is its complete XML markup, including the target and data.
       # @return [String] frozen owned text snapshot
       attr_reader :content
 
@@ -98,8 +115,9 @@ module Sevgi
       # @return [String] owned element name
       attr_reader :name
 
-      # Returns immutable namespace declarations emitted for this node. A conversion root owns its local declarations;
-      # a separately selected node owns all declarations in scope; descendant snapshots own their local declarations.
+      # Returns immutable namespace declarations emitted for this node. A conversion root owns its local declarations.
+      # A separately selected node owns all declarations in scope. Descendant snapshots own their local declarations.
+      # Independent source conversion and evaluation also emit the inherited declarations captured for that node.
       # @return [Hash{String => String}] frozen owned namespace snapshot
       attr_reader :namespaces
 
@@ -128,20 +146,22 @@ module Sevgi
 
       alias meta _
 
-      # Converts this node into formatted Sevgi DSL Ruby source.
+      # Converts this node into formatted Sevgi DSL Ruby source. The returned String is ordinary Ruby source. Review and
+      # integrate it statically rather than using Ruby's raw dynamic evaluation methods.
       # @return [String] formatted Sevgi DSL source
       # @raise [Sevgi::PanicError] when generated Ruby source cannot be formatted
       # @note Foreign namespace elements use the explicit `Element` DSL path, and nested `svg` nodes remain elements.
       # @note Unsafe bare Ruby names are emitted through the explicit `Element` DSL word.
-      def derender = Ruby.format(decompile(@pres).join("\n"))
+      def derender = Ruby.format(decompile(@pres, namespaces: @scope).join("\n"))
 
       # Evaluates this node under a graphics element.
       # @param element [Sevgi::Graphics::Element] target graphics element
       # @return [Sevgi::Graphics::Element, nil] included current element, or nil when it produces no graphics output
       # @note Namespace declarations, qualified attributes, significant text, and nested `svg` nodes are preserved.
-      def evaluate(element) = Evaluator.new(element).append(self)
+      def evaluate(element) = Evaluator.new(element).append(self, namespaces: @scope)
 
       # Evaluates only this node's children under a graphics element.
+      # Each imported element retains its namespace scope without changing the target parent's declarations.
       # @param element [Sevgi::Graphics::Element] target graphics element
       # @return [Array<Sevgi::Graphics::Element>] immutable included-child snapshot
       def evaluate_children(element) = children.filter_map { it.evaluate(element) }.freeze
@@ -165,36 +185,34 @@ module Sevgi
 
       attr_reader :node, :type
 
-      def all_attributes = {**attributes, **namespaces}.freeze
+      def all_attributes(namespaces = self.namespaces()) = {**attributes, **namespaces}.freeze
 
       def attribute_key(attribute) = [attribute.namespace&.prefix, attribute.name].compact.join(":")
 
       def dispatch
-        case
-        when node.text?
-          :Text
-        when node.comment?
-          :Junk
-        when Namespace.svg?(node, "style")
+        type = NODE_TYPES[node.type]
+        type ||= if Namespace.svg?(node, "style") && node.children.all? { it.text? || it.cdata? }
           :CSS
-        when @top && Namespace.svg?(node, "svg")
+        elsif @top && Namespace.svg?(node, "svg")
           :Root
         else
           :Any
         end
-          .tap { extend(Elements.const_get(it)) }
+
+        type.tap { extend(Elements.const_get(it)) }
       end
 
       def element = name
 
       def ignorable_child?(child)
-        child.send(:type) == :Junk ||
-          (child.send(:text?) &&
-            child.content.strip.empty? &&
-            !child.send(:preserve_space?) &&
-            !child.send(:inline_text?))
+        child.send(:text?) &&
+          child.content.strip.empty? &&
+          !child.send(:preserve_space?) &&
+          !child.send(:inline_text?)
       end
 
+      def literal_content? = node.cdata? || node.comment?
+
       def preserve_space?
         each_node do |current|
           case xml_space(current)
@@ -210,6 +228,12 @@ module Sevgi
 
       def inline_text? = mixed_text? && !node.content.match?(/[\r\n]/)
 
+      def inline_content?
+        return false unless children.any? { it.send(:text?) || it.send(:type) == :CData }
+
+        preserve_space? || node.children.none? { it.text? && it.content.match?(/[\r\n]/) }
+      end
+
       def normalized_content
         return node.content if mixed_text? && inline_text?
         return node.content.strip unless mixed_text?
@@ -217,7 +241,10 @@ module Sevgi
         node.content.sub(/\A[ \t]*\r?\n[ \t]*/, "").sub(/[ \t]*\r?\n[ \t]*\z/, "")
       end
 
-      def mixed_text? = node.text? && node.parent&.children&.any?(&:element?)
+      def mixed_text?
+        node.text? &&
+          node.parent&.children&.any? { it.element? || it.cdata? || it.comment? || it.processing_instruction? }
+      end
 
       def local_namespaces
         return {} unless node.respond_to?(:namespace_definitions)
@@ -238,6 +265,8 @@ module Sevgi
 
       def text? = node.text?
 
+      def text_leaf? = children.one? && children.first.send(:text?)
+
       def xml_space(current)
         return unless current.respond_to?(:attribute_nodes)
 

data/lib/sevgi/derender/version.rb

@@ -3,6 +3,6 @@
 module Sevgi
   module Derender
     # Current version of the Sevgi derender gem.
-    VERSION = "0.98.2"
+    VERSION = "1.0.0"
   end
 end

data/lib/sevgi/derender.rb

@@ -13,8 +13,8 @@ require_relative "derender/version"
 module Sevgi
   # Brings editor-authored SVG/XML into programmatic Sevgi workflows.
   #
-  # Vector geometry such as a Bezier-heavy logo or hand-adjusted illustration may be better authored in a visual editor
-  # than reconstructed as Ruby. Derender preserves that SVG/XML tree as inspectable data, formatted Sevgi DSL source,
+  # Some vector geometry is easier to create in a visual editor than to reconstruct as Ruby. Examples include a
+  # Bezier-heavy logo and a hand-adjusted illustration. Derender preserves that SVG/XML tree as inspectable data,
   # or graphics elements under an existing document. This lets editor-authored geometry participate in programmatic
   # composition, styling, layout, and output. Use it when SVG/XML is a real input artifact, not as an intermediate
   # authoring format for ordinary Sevgi drawing code.
@@ -24,16 +24,23 @@ module Sevgi
   # tree without invoking same-named Ruby methods.
   #
   # Evaluation APIs treat SVG/XML as data: they build graphics element trees directly and do not execute generated Ruby
-  # source. Malformed, rootless, or unmatched input is rejected with {Sevgi::ArgumentError}.
+  # source. The String returned by source-generation APIs is ordinary Ruby source. Review and integrate it statically
+  # rather than passing it to Ruby's raw dynamic evaluation methods. Malformed, rootless, or unmatched input is rejected
+  # with {Sevgi::ArgumentError}.
+  # Processing instructions retain their target, data, and order as inert XML markup. Custom entity references in the
+  # selected subtree are rejected before inclusion changes a target. Predefined and numeric references remain valid.
+  # Whole-document conversion rejects nodes after the root. Explicit id selection ignores unrelated document siblings.
+  # Input uses the XML encoding declaration or byte-order mark. Generated source and rendered XML use UTF-8.
+  # The XML declaration retains its version and standalone flag, with any encoding field changed to UTF-8.
   #
   # Namespace dispatch treats qualified and foreign elements as ordinary XML nodes. Their element identity, namespace
   # declarations, qualified attributes, significant text, and nested `svg` elements survive source generation and direct
   # evaluation. CSS specialization applies only to unqualified `style` elements in no namespace or the default SVG
-  # namespace; the document-root strategy additionally requires an unqualified `svg` at the root of the conversion.
+  # namespace. The document-root strategy also requires an unqualified `svg` at the root of the conversion.
   # Simple CSS rules use the readable `css({...})` DSL form. At-rules, duplicate declarations, and other CSS that cannot
   # be represented losslessly as a Hash remain owned raw style content.
   #
-  # Attribute omission uses exact, case-sensitive names across the selected subtree. ID selection happens first;
+  # Attribute omission uses exact, case-sensitive names across the selected subtree. ID selection happens first.
   # namespace declarations remain intact, and omitting the `style` attribute does not omit `style` elements.
   #
   # @example Inspect, select, and convert an immutable result
@@ -82,7 +89,8 @@ module Sevgi
     # @see Sevgi.DecompileFile
     def self.decompile_file(file, id: nil, omit: nil) = Document.load_file(file).decompile(id, omit:)
 
-    # Converts SVG/XML content into Sevgi DSL Ruby source.
+    # Converts SVG/XML content into Sevgi DSL Ruby source. The returned String is ordinary Ruby source. Review and
+    # integrate it statically rather than using Ruby's raw dynamic evaluation methods.
     # @param content [String] SVG/XML source content
     # @param id [String, Symbol, nil] optional SVG id selecting a node inside the source
     # @param omit [String, Symbol, Array<String, Symbol>, nil] exact attribute name or names omitted from the selected
@@ -100,7 +108,8 @@ module Sevgi
     # @see Sevgi.Derender
     def self.derender(content, id: nil, omit: nil) = Document.new(content).decompile(id, omit:).derender
 
-    # Converts an SVG/XML file into Sevgi DSL Ruby source.
+    # Converts an SVG/XML file into Sevgi DSL Ruby source. The returned String is ordinary Ruby source. Review and
+    # integrate it statically rather than using Ruby's raw dynamic evaluation methods.
     # @param file [String] path to the source SVG/XML file
     # @param id [String, Symbol, nil] optional SVG id selecting a node inside the source
     # @param omit [String, Symbol, Array<String, Symbol>, nil] exact attribute name or names omitted from the selected

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sevgi-derender
 version: !ruby/object:Gem::Version
-  version: 0.98.2
+  version: 1.0.0
 platform: ruby
 authors:
 - Recai Oktaş
@@ -15,28 +15,28 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.98.2
+        version: 1.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.98.2
+        version: 1.0.0
 - !ruby/object:Gem::Dependency
   name: sevgi-graphics
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.98.2
+        version: 1.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.98.2
+        version: 1.0.0
 - !ruby/object:Gem::Dependency
   name: css_parser
   requirement: !ruby/object:Gem::Requirement
@@ -96,8 +96,9 @@ files:
 - lib/sevgi/derender/document.rb
 - lib/sevgi/derender/elements.rb
 - lib/sevgi/derender/elements/any.rb
+- lib/sevgi/derender/elements/comment.rb
 - lib/sevgi/derender/elements/css.rb
-- lib/sevgi/derender/elements/junk.rb
+- lib/sevgi/derender/elements/instruction.rb
 - lib/sevgi/derender/elements/root.rb
 - lib/sevgi/derender/elements/text.rb
 - lib/sevgi/derender/evaluator.rb
@@ -126,7 +127,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: SVG-to-Sevgi source conversion.
 test_files: []

data/lib/sevgi/derender/elements/junk.rb

@@ -1,15 +0,0 @@
-# frozen_string_literal: true
-
-module Sevgi
-  module Derender
-    module Elements
-      # Element strategy for comments and ignored XML nodes.
-      # @api private
-      module Junk
-        # Drops ignored nodes from generated source.
-        # @return [Array<String>] empty source lines
-        def decompile(*) = []
-      end
-    end
-  end
-end