sevgi-derender 0.95.0 → 0.98.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 84e2eb700b9e867ffb80ad1223ba2bfaf32f632b19d05a07db71191a8a611cac
-  data.tar.gz: 7cefed91f1645a9c195dd65d677f7c9cb041f6f4f4093b90aae2aa56a848342b
+  metadata.gz: 9d9e616e1b10140f4e9477ca8cc23f7912d56a6169b4e686a74353c816fe9706
+  data.tar.gz: e32b3958b5270380a74f218d87377a6fca87db2cfd3c518cd28530fcb7f97746
 SHA512:
-  metadata.gz: fa91f3c9a83fa0b8a6edfa104131e8fcd533421bd182818713c3235c046b431926a031d2a3b52803afb4150f1757ace6b50f42977ef6065b39cbb3ea2f5bad94
-  data.tar.gz: da2e1ce83ee737df97b9dd01b80abb2d372f2315eab3e6051b1cb563120185afd7f326b158f869760cdc71c623a1bd9e12b2dd82c05c056ced7b0e469ea78b42
+  metadata.gz: '058bc5a453580bc9c32fd86a1d6a64474868c18b1ffe0af32ceb40d52a60263cfa1a787e1fac9f521ef31817f8a81991ddb65a33503a8b24e3743996f2dcd468'
+  data.tar.gz: eb906f2cb811fbbe73abeec77b298f68ee3db1de17366996762f02f4e36c0e5d392139cf83b4bc686d7fd7a156838065313fe1e7110d918dc3b45fe2a081fc85

data/CHANGELOG.md

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

data/README.md

@@ -1,6 +1,6 @@
 # Sevgi Derender
 
-Converts SVG/XML content back into Sevgi DSL source.
+Sevgi Derender converts SVG or XML back into Sevgi DSL source.
 
 ## Install
 
@@ -19,26 +19,41 @@ require "sevgi/derender"
 ```ruby
 source = "<svg><rect width=\"3\" height=\"5\"/></svg>"
 Sevgi::Derender.derender(source)
+
+source = '<svg><rect id="mark" style="fill: red" width="3"/></svg>'
+Sevgi::Derender.derender(source, omit: %i[id style])
 ```
 
 ## Executable
 
 ```sh
-igves drawing.svg
+igves --omit id --omit style drawing.svg
+```
+
+Omit the file or pass `-` to read SVG from standard input:
+
+```sh
+igves --omit id < drawing.svg
+```
+
+`igves` prints generated Sevgi source. The umbrella `sevgi` gem also installs `igsev`, which evaluates that source and
+prints normalized SVG:
+
+```sh
+igsev --omit id --omit style < drawing.svg
 ```
 
 ## Ruby compatibility
 
-Requires Ruby 3.4.0 or newer. CI verifies Ruby 3.4.0 and the current development Ruby from `.ruby-version`.
+Requires Ruby 3.4.0 or newer. CI verifies the current Ruby 3.4 release and the development Ruby from `.ruby-version`.
 
 ## Native prerequisites
 
-None beyond Ruby and this gem's Ruby dependencies. Nokogiri may use platform packages depending on the target Ruby
-platform.
+This gem needs no native libraries of its own. Nokogiri may use platform packages depending on the target Ruby platform.
 
 ## Links
 
-- Documentation: https://sevgi.roktas.dev
-- API documentation: https://www.rubydoc.info/gems/sevgi-derender
-- Source: https://github.com/roktas/sevgi/tree/main/derender
-- Changelog: https://github.com/roktas/sevgi/blob/main/CHANGELOG.md
+- Documentation: <https://sevgi.roktas.dev>
+- API documentation: <https://www.rubydoc.info/gems/sevgi-derender>
+- Source: <https://github.com/roktas/sevgi/tree/main/derender>
+- Changelog: <https://github.com/roktas/sevgi/blob/main/CHANGELOG.md>

data/bin/igves

@@ -3,4 +3,4 @@
 
 require "sevgi/binaries/igves"
 
-Sevgi::Binaries::Igves.(ARGV)
+Sevgi.const_get(:Binaries, false)::Igves.(ARGV)

data/lib/sevgi/binaries/igves.rb

@@ -3,8 +3,11 @@
 require "sevgi"
 
 module Sevgi
+  # Command-line entrypoint implementations shipped with Sevgi.
+  # @api private
   module Binaries
     # Implements the `igves` executable that converts SVG files into Sevgi DSL source.
+    # @api private
     module Igves
       extend self
 
@@ -14,16 +17,33 @@ module Sevgi
       # Error raised for invalid command-line usage.
       Error = Class.new(::Sevgi::Error)
 
+      FLAGS = {
+        "--exception" => :vomit,
+        "--help" => :help,
+        "--version" => :version,
+        "-h" => :help,
+        "-v" => :version,
+        "-x" => :vomit
+      }.freeze
+      private_constant :FLAGS
+
       # Parsed command-line options for the `igves` executable.
       # @api private
-      Options = Struct.new(:vomit, :help, :version) do
+      Options = Struct.new(:vomit, :help, :version, :omit) do
         # Parses command-line options and removes them from the argv array.
         # @param argv [Array<String>] mutable command-line argument array
         # @return [Sevgi::Binaries::Igves::Options] parsed options
         # @raise [Sevgi::Binaries::Igves::Error] when an option is not recognized
         def self.parse(argv)
           new.tap do |options|
-            argv.first.start_with?("-") ? option(argv, options) : break until argv.empty?
+            until argv.empty? || argv.first == "-" || !argv.first.start_with?("-")
+              if argv.first == "--"
+                argv.shift
+                break
+              end
+
+              option(argv, options)
+            end
           end
         end
 
@@ -31,16 +51,11 @@ module Sevgi
           private
 
           def option(argv, options)
-            case (arg = argv.shift)
-            when "-x", "--exception"
-              options.vomit = true
-            when "-h", "--help"
-              options.help = true
-            when "-v", "--version"
-              options.version = true
-            else
-              Error.("Not a valid option: #{arg}")
-            end
+            arg = argv.shift
+            return options[FLAGS[arg]] = true if FLAGS.key?(arg)
+            return (options.omit ||= []) << (argv.shift || Error.("No attribute given for --omit")) if arg == "--omit"
+
+            Error.("Not a valid option: #{arg}")
           end
         end
       end
@@ -53,11 +68,11 @@ module Sevgi
       # @raise [Sevgi::ArgumentError] when the SVG file cannot be found
       # @raise [Sevgi::PanicError] when generated Ruby source cannot be formatted
       # @raise [StandardError] when `--exception` or `SEVGI_VOMIT` requests raw errors
-      # @raise [SystemExit] when command-line usage aborts
+      # @raise [SystemExit] when argv does not match `[options...] [--] [file|-]` or command-line usage aborts
       def call(argv)
         dispatch(Array(argv))
       rescue Binaries::Igves::Error => e
-        abort(e.message)
+        abort("#{e.message}\n\n#{help}")
       end
 
       private
@@ -67,7 +82,7 @@ module Sevgi
         return puts(help) if options.help
         return puts(::Sevgi::VERSION) if options.version
 
-        print_file(argv.shift, options)
+        print_file(operand(argv), options)
       rescue Binaries::Igves::Error
         raise
       rescue ::StandardError => e
@@ -92,22 +107,32 @@ module Sevgi
 
       def help
         <<~HELP
-          Usage: #{PROGNAME} [options...] <SVG file>
+          Usage: #{PROGNAME} [options...] [--] [SVG file|-]
 
           See documentation for detailed help.
 
           Options:
 
+              --omit ATTRIBUTE  Omit an attribute (repeatable)
           -x, --exception       Raise exception instead of abort
+              --                Stop option parsing
+
           -h, --help            Show this help
           -v, --version         Display version
         HELP
       end
 
-      def run(file, _options)
-        Error.("No SVG file given.") unless file
+      def operand(argv)
+        file = argv.shift
+        Error.("Unexpected argument: #{argv.first}") unless argv.empty?
 
-        Derender.derender_file(file)
+        file unless file == "-"
+      end
+
+      def run(file, options)
+        return Derender.derender_file(file, omit: options.omit) if file
+
+        Derender.derender($stdin.read, omit: options.omit)
       end
 
       def print_file(file, options)
@@ -125,4 +150,6 @@ module Sevgi
       end
     end
   end
+
+  private_constant :Binaries
 end

data/lib/sevgi/derender/attributes.rb

@@ -38,8 +38,12 @@ module Sevgi
             key = Css.to_key(key) if key.is_a?(::String)
 
             if key == "style"
-              style = Css.to_h!(value)
-              style.empty? ? "{}" : "{ #{Attributes.decompile(style)} }"
+              style = Css.declarations(value)
+              if style
+                style.empty? ? "{}" : "{ #{Attributes.decompile(style)} }"
+              else
+                Ruby.literal(value)
+              end
             elsif value.is_a?(::String)
               Css.to_value(value)
             elsif value.is_a?(::Hash)

data/lib/sevgi/derender/document.rb

@@ -5,6 +5,7 @@ require "nokogiri"
 module Sevgi
   module Derender
     # Parsed SVG/XML document wrapper used by the derender pipeline.
+    # @api private
     class Document
       # Loads and parses an SVG/XML file.
       #
@@ -13,7 +14,7 @@ module Sevgi
       # @param path [String] path to the source file, with or without `.svg` extension
       # @return [Sevgi::Derender::Document] document wrapper
       # @raise [Sevgi::ArgumentError] when the file cannot be found or file content is malformed XML
-      # @raise [Errno::EACCES] when the file cannot be read
+      # @raise [SystemCallError] when the file cannot be read
       def self.load_file(path)
         entry = ::File.expand_path(F.qualify(path, "svg"))
 
@@ -65,10 +66,11 @@ module Sevgi
       end
 
       # Converts the root or selected node into a derender node.
-      # @param id [String, nil] optional SVG id selecting a node inside the document
+      # @param id [String, Symbol, nil] optional SVG id selecting a node inside the document
+      # @param omit [String, Symbol, Array<String, Symbol>, nil] attribute name or names omitted from the selected subtree
       # @return [Sevgi::Derender::Node] selected node in the derender tree
       # @raise [Sevgi::ArgumentError] when the document has no root element or the id is absent
-      def decompile(id = nil)
+      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")
@@ -81,7 +83,7 @@ module Sevgi
 
         ArgumentError.("XML document has no root element") unless element
 
-        Node.new(element, pres, namespaces: namespace_scope(element))
+        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
@@ -109,6 +111,10 @@ module Sevgi
         end
       end
 
+      def omissions(value)
+        Array(value).to_h { [it.to_s.dup.freeze, true] }.freeze
+      end
+
       def xpath_literal(value)
         value = value.to_s
 

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

@@ -10,7 +10,7 @@ module Sevgi
         # @return [Array<String>] unformatted Ruby source lines
         def decompile(*)
           if children.any?
-            children.one? && children.first.node.text? ? Array(leaf(has_attributes: attributes.any?)) : tree
+            children.one? && children.first.send(:text?) ? Array(leaf(has_attributes: attributes.any?)) : tree
           else
             Array(leaf(has_content: false))
           end
@@ -19,7 +19,7 @@ module Sevgi
         private
 
         def leaf(has_content: true, has_attributes: true)
-          attributes = attributes!
+          attributes = all_attributes
           args = []
           args << Ruby.literal(content) if has_content
           args << Attributes.decompile(attributes) if has_attributes && attributes.any?
@@ -40,7 +40,7 @@ module Sevgi
         def tree
           [
             "#{leaf(has_content: false)} do",
-            *children.map(&:decompile).flatten,
+            *children.map { it.send(:decompile) }.flatten,
             "end"
           ]
         end

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

@@ -9,20 +9,27 @@ module Sevgi
         # Converts a style node into unformatted Sevgi DSL lines.
         # @return [Array<String>] unformatted Ruby source lines
         def decompile(*)
-          return [] unless (lines = css_lines)
+          return raw_style unless (lines = css_lines)
 
           [
             "css({",
             *lines,
-            "})",
+            "}, #{css_attributes})",
             ""
           ]
         end
 
         private
 
+        def css_attributes
+          attributes = all_attributes
+          source = Attributes.decompile(attributes)
+
+          attributes.key?("type") ? source : [source, "type: nil"].reject(&:empty?).join(", ")
+        end
+
         def css_lines
-          return unless (hash = Css.to_h(node.content))
+          return unless (hash = Css.rules(node.content))
 
           hash
             .map do |selector, declarations|
@@ -34,6 +41,13 @@ module Sevgi
             end
             .flatten
         end
+
+        def raw_style
+          arguments = ["Sevgi::Graphics::Content.cdata(#{Ruby.literal(node.content)})"]
+          arguments << Attributes.decompile(all_attributes) if all_attributes.any?
+
+          ["style #{arguments.join(", ")}", ""]
+        end
       end
     end
   end

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

@@ -17,7 +17,7 @@ module Sevgi
 
           lines.unshift(
             [
-              "SVG.document preambles: [",
+              "SVG.Document preambles: [",
               *pres.map { "#{Ruby.literal(it)}," },
               "]",
               ""
@@ -29,9 +29,6 @@ module Sevgi
         # @return [String]
         def element = "SVG"
 
-        # Returns root attributes merged with namespace declarations.
-        # @return [Hash{String => String}] attributes and namespaces
-        def attributes! = {**attributes, **namespaces}
       end
     end
   end

data/lib/sevgi/derender/evaluator.rb

@@ -14,7 +14,7 @@ module Sevgi
       # @param node [Sevgi::Derender::Node] derender node
       # @return [Sevgi::Graphics::Element, nil] included element, or nil when the node does not produce graphics output
       def append(node)
-        case node.type
+        case node.send(:type)
         when :CSS
           append_css(node)
         when :Text
@@ -29,21 +29,33 @@ module Sevgi
       attr_reader :parent
 
       def append_css(node)
-        return unless (hash = Css.to_h(node.node.content))
+        content = if (hash = Css.rules(node.content))
+          Graphics::Content.css(hash)
+        else
+          Graphics::Content.cdata(node.content)
+        end
 
-        build(:style, Graphics::Content.css(hash), type: "text/css", **node.attributes)
+        build(:style, content, **node.send(:all_attributes))
       end
 
       def append_element(node)
         contents = contents(node)
 
-        build(node.name, *contents, **node.attributes!).tap do |element|
+        build(node.name, *contents, **attributes(node)).tap do |element|
           node.children.each { self.class.new(element).append(it) } if contents.empty?
         end
       end
 
+      def attributes(node)
+        attributes = node.send(:all_attributes)
+        return attributes unless (style = attributes["style"])
+        return attributes unless (declarations = Css.declarations(style))
+
+        {**attributes, "style" => declarations}
+      end
+
       def contents(node)
-        node.children.one? && node.children.first.node.text? ? [node.content] : []
+        node.children.one? && node.children.first.send(:text?) ? [node.content] : []
       end
 
       def build(name, *contents, **attributes)

data/lib/sevgi/derender/internal.rb

@@ -27,6 +27,30 @@ module Sevgi
         hash ? hash.fetch("*", {}) : {}
       end
 
+      # Returns CSS rules only when Hash conversion preserves the source declarations.
+      # @param css_string [String] CSS rule source
+      # @return [Hash, nil] losslessly representable rules, or nil
+      def rules(css_string)
+        parsed = to_h(css_string)
+        sourced = source_rules(css_string)
+
+        parsed if parsed == sourced
+      rescue ::StandardError
+        nil
+      end
+
+      # Returns inline declarations only when Hash conversion preserves the source declarations.
+      # @param style_string [String] inline CSS declaration source
+      # @return [Hash, nil] losslessly representable declarations, or nil
+      def declarations(style_string)
+        parsed = to_h!(style_string)
+        sourced = source_declarations(style_string)
+
+        parsed if parsed == sourced
+      rescue ::StandardError
+        nil
+      end
+
       # Converts a CSS key into a Ruby hash key.
       # @param arg [String] CSS key
       # @return [String] Ruby hash key source
@@ -43,6 +67,47 @@ module Sevgi
       # @return [String] Ruby literal or numeric source
       def to_value(arg) = (arg.to_f.to_s == arg) || (arg.to_i.to_s == arg) ? arg : arg.inspect
 
+      private
+
+      def source_declarations(source)
+        declarations = source.split(";", -1).map(&:strip).reject(&:empty?)
+        pairs = declarations.map { source_declaration(it) }
+        return if pairs.any?(&:nil?)
+        return unless pairs.map(&:first).uniq.size == pairs.size
+
+        pairs.to_h
+      end
+
+      def source_declaration(source)
+        key, value = source.split(":", 2).map(&:strip)
+
+        [key, value] if key && value && !key.empty? && !value.empty?
+      end
+
+      def source_rules(source)
+        source = source.dup
+        rules = {}
+
+        until source.strip.empty?
+          selector, declarations, source = source_rule(source)
+          return unless selector && !rules.key?(selector)
+
+          rules[selector] = declarations
+        end
+
+        rules
+      end
+
+      def source_rule(source)
+        match = /\A\s*([^{}]+?)\s*\{([^{}]*)\}\s*/m.match(source)
+        return [nil, nil, source] unless match
+
+        selector = match[1].strip
+        declarations = source_declarations(match[2])
+        selector = nil if selector.empty? || selector.start_with?("@") || declarations.nil?
+        [selector, declarations, match.post_match]
+      end
+
       extend self
     end
 
@@ -133,11 +198,17 @@ module Sevgi
       private
 
       def receiver_collision?(name)
-        document = Graphics::Document.const_get(:Base, false)
+        documents = [Graphics::Document::Proto]
+        documents.concat(Graphics::Document.keys.map { Graphics::Document.fetch(it) })
 
-        document.ancestors.any? do |ancestor|
-          ancestor.method_defined?(name, false) || ancestor.private_method_defined?(name, false)
-        end
+        documents.uniq.any? { effective_collision?(it, name) }
+      end
+
+      def effective_collision?(document, name)
+        return false unless document.method_defined?(name) || document.private_method_defined?(name)
+
+        method = document.instance_method(name)
+        method.owner != Graphics::Element || !Graphics::Element.send(:element_method?, name)
       end
 
       extend self

data/lib/sevgi/derender/node.rb

@@ -19,121 +19,153 @@ module Sevgi
 
     private_constant :Namespace
 
-    # Node in a derender tree produced from an SVG/XML node.
+    META_NAMESPACE = "_:"
+    private_constant :META_NAMESPACE
+
+    # Captures owned Node state during construction.
+    # @api private
+    module Capture
+      private
+
+      def capture_context(pres, namespaces)
+        @pres = pres.map { it.to_s.dup.freeze }.freeze
+        @namespaces = snapshot(namespaces || local_namespaces)
+        @type = dispatch
+        singleton_class.send(:private, :decompile)
+      end
+
+      def capture_children
+        @children = node
+          .children
+          .map { self.class.send(:new, it, omit: @omit, top: false) }
+          .reject { ignorable_child?(it) }
+          .freeze
+      end
+
+      def capture_values
+        @attributes = snapshot(
+          node.attribute_nodes.filter_map do |attribute|
+            key = attribute_key(attribute)
+            [key, attribute.value] unless @omit.key?(key)
+          end
+        )
+        @meta = snapshot(attributes.filter_map { |key, value| metadata(key, value) })
+      end
+
+      def capture_identity
+        @content = (preserve_space? ? node.content : normalized_content).dup.freeze
+        @name = [node.namespace&.prefix, node.name].compact.join(":").freeze
+      end
+
+      def metadata(key, value)
+        [key.delete_prefix(META_NAMESPACE), value] if key.start_with?(META_NAMESPACE)
+      end
+
+      def snapshot(pairs)
+        pairs
+          .each_with_object({}) do |(key, value), result|
+            result[key.to_s.dup.freeze] = value.to_s.dup.freeze
+          end
+          .freeze
+      end
+    end
+
+    private_constant :Capture
+
+    # Immutable conversion result for one SVG/XML node.
+    #
+    # 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
-      # Returns the source XML node.
-      # @return [Nokogiri::XML::Node]
-      attr_reader :node
+      include Capture
+
+      private_class_method :new
 
-      # Returns preamble XML lines carried by the root node.
-      # @return [Array<String>]
-      attr_reader :pres
+      # Returns immutable XML attributes.
+      # @return [Hash{String => String}] owned attribute snapshot
+      attr_reader :attributes
 
-      # Returns the dispatch type used by derender element strategies.
-      # @return [Symbol]
-      attr_reader :type
+      # Returns immutable child nodes.
+      # @return [Array<Sevgi::Derender::Node>] owned child snapshot
+      attr_reader :children
 
-      # Builds a derender node.
+      # 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.
+      # @return [String] frozen owned text snapshot
+      attr_reader :content
+
+      # Returns the immutable qualified element name.
+      # @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.
+      # @return [Hash{String => String}] frozen owned namespace snapshot
+      attr_reader :namespaces
+
+      # Builds an owned derender result.
       # @param node [Nokogiri::XML::Node] source XML node
       # @param pres [Array<String>] preamble XML lines carried by the root node
-      # @param namespaces [Hash{String => String}, nil] namespace declarations to emit on this node; selected roots use
-      #   their full inherited namespace scope, while ordinary children use only declarations from their own element
+      # @param namespaces [Hash{String => String}, nil] namespace declarations to emit on this node
+      # @param omit [Hash{String => Boolean}, nil] normalized attribute omission set shared by the captured subtree
       # @param top [Boolean] true when this node is the root of the current conversion
       # @return [void]
-      def initialize(node, pres = [], namespaces: nil, top: true)
+      # @api private
+      def initialize(node, pres = [], namespaces: nil, omit: nil, top: true)
         @node = node
-        @pres = pres
-        @namespaces = namespaces
+        @omit = omit || {}.freeze
         @top = top
-        @type = dispatch
+        capture_context(pres, namespaces)
+        capture_values
+        capture_children
+        capture_identity
+        freeze
       end
 
-      # Attribute namespace prefix used for Sevgi metadata.
-      META_NAMESPACE = "_:"
-
       # Returns Sevgi metadata attributes without the metadata namespace prefix.
-      # @return [Hash{String => String}] metadata attributes
-      def _
-        @_ ||= attributes
-          .slice(
-            *attributes.keys.select { |key| key.start_with?(META_NAMESPACE) }
-          )
-          .transform_keys! { |key| key.delete_prefix(META_NAMESPACE) }
-      end
+      # @return [Hash{String => String}] immutable metadata snapshot
+      def _ = @meta
 
       alias meta _
 
-      # Returns source XML attributes keyed with namespace prefixes when present.
-      # @return [Hash{String => String}] XML attributes
-      def attributes = @attributes ||= node.attribute_nodes.to_h { [attribute_key(it), it.value] }
-
-      # Returns source XML attributes and namespace declarations emitted on this node.
-      # @return [Hash{String => String}] XML attributes
-      def attributes! = {**attributes, **namespaces}
-
-      # Returns non-ignorable child derender nodes.
-      # @return [Array<Sevgi::Derender::Node>] child nodes
-      def children = @children ||= node.children.map { self.class.new(it, top: false) }.reject { ignorable_child?(it) }
-
-      # Returns node text content.
-      #
-      # `xml:space="preserve"` keeps content verbatim. Default-space text nodes are stripped for ordinary pretty-printed
-      # content; line-break indentation around mixed-content children is removed while inline boundary spaces and tabs are
-      # kept because they affect rendered SVG text.
-      # @return [String]
-      def content = @content ||= preserve_space? ? node.content : normalized_content
-
       # Converts this node into formatted Sevgi DSL Ruby source.
       # @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"))
-
-      # Returns the Sevgi DSL element name for this node.
-      # @return [String]
-      def element = name
+      def derender = Ruby.format(decompile(@pres).join("\n"))
 
       # Evaluates this node under a graphics element.
       # @param element [Sevgi::Graphics::Element] target graphics element
-      # @param include_current [Boolean] true to evaluate this node, false to evaluate only children
-      # @return [Sevgi::Graphics::Element, Array<Sevgi::Graphics::Element>, nil] included current element, included child
-      #   elements when include_current is false, or nil when the node does not produce graphics output
+      # @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, include_current = true)
-        return Evaluator.new(element).append(self) if include_current
-
-        evaluate_children(element)
-      end
+      def evaluate(element) = Evaluator.new(element).append(self)
 
       # Evaluates only this node's children under a graphics element.
       # @param element [Sevgi::Graphics::Element] target graphics element
-      # @return [Array<Sevgi::Graphics::Element>] included child elements
-      def evaluate_children(element) = children.map { it.evaluate(element) }.compact
+      # @return [Array<Sevgi::Graphics::Element>] immutable included-child snapshot
+      def evaluate_children(element) = children.filter_map { it.evaluate(element) }.freeze
 
-      # Finds the first descendant whose attribute matches a value.
+      # Finds this node or the first descendant whose attribute matches a value.
       # @param arg [String] attribute value to find
       # @param by [String] attribute name used for lookup
-      # @return [Sevgi::Derender::Node, nil] matching node, or nil
+      # @return [Sevgi::Derender::Node, nil] matching immutable node, or nil
+      # @note Attributes omitted during decompilation are unavailable for later searches.
       def find(arg, by: "id")
         return self if attributes[by] == arg
 
         children.lazy.map { it.find(arg, by:) }.find(&:itself)
       end
 
-      # Returns the source XML qualified name, including its namespace prefix when present.
-      # @return [String]
-      def name = @name ||= [node.namespace&.prefix, node.name].compact.join(":")
+      # Reports whether this node represents an SVG document root.
+      # @return [Boolean] true for the conversion root strategy
+      def root? = @type == :Root
 
-      # Returns source XML namespace declarations emitted on this node.
-      # @return [Hash{String => String}] namespace declarations
-      def namespaces = (@namespaces ||= local_namespaces)
+      private
 
-      # Reports whether this node is the SVG root strategy.
-      # @return [Boolean]
-      def root? = type == :Root
+      attr_reader :node, :type
 
-      private
+      def all_attributes = {**attributes, **namespaces}.freeze
 
       def attribute_key(attribute) = [attribute.namespace&.prefix, attribute.name].compact.join(":")
 
@@ -153,13 +185,16 @@ module Sevgi
           .tap { extend(Elements.const_get(it)) }
       end
 
+      def element = name
+
       def ignorable_child?(child)
-        child.type == :Junk ||
-          (child.node.text? && child.node.text.strip.empty? && !child.preserve_space? && !child.inline_text?)
+        child.send(:type) == :Junk ||
+          (child.send(:text?) &&
+            child.content.strip.empty? &&
+            !child.send(:preserve_space?) &&
+            !child.send(:inline_text?))
       end
 
-      protected
-
       def preserve_space?
         each_node do |current|
           case xml_space(current)
@@ -175,8 +210,6 @@ module Sevgi
 
       def inline_text? = mixed_text? && !node.content.match?(/[\r\n]/)
 
-      private
-
       def normalized_content
         return node.content if mixed_text? && inline_text?
         return node.content.strip unless mixed_text?
@@ -203,6 +236,8 @@ module Sevgi
         end
       end
 
+      def text? = node.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.95.0"
+    VERSION = "0.98.2"
   end
 end

data/lib/sevgi/derender.rb

@@ -11,7 +11,13 @@ require_relative "derender/node"
 require_relative "derender/version"
 
 module Sevgi
-  # Converts SVG/XML content into Sevgi DSL source or evaluates it into graphics elements.
+  # 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,
+  # 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.
   #
   # Generated source uses bare DSL calls only for recognized element names that cannot dispatch to an existing Ruby or
   # Sevgi method. Other XML names use the explicit `Element` DSL word so executing generated source preserves the XML
@@ -24,154 +30,166 @@ module Sevgi
   # 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.
+  # 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;
+  # namespace declarations remain intact, and omitting the `style` attribute does not omit `style` elements.
+  #
+  # @example Inspect, select, and convert an immutable result
+  #   result = Sevgi::Derender.decompile('<svg><rect id="mark" width="10"/></svg>')
+  #   mark = result.find("mark")
+  #   mark.attributes #=> {"id"=>"mark", "width"=>"10"}
+  #   mark.derender   #=> "rect id: \"mark\", width: 10\n"
+  # @example Preserve an at-rule as raw style content
+  #   Sevgi::Derender.derender("<style>@media print { rect { fill: black; } }</style>")
+  #   #=> "style Sevgi::Graphics::Content.cdata(\"@media print { rect { fill: black; } }\")\n"
+  # @example Select a node while omitting editor-only attributes
+  #   source = '<svg><g id="mark" style="fill: red"><rect/></g></svg>'
+  #   Sevgi::Derender.derender(source, id: "mark", omit: %i[id style])
+  #   #=> "g do\n  rect\nend\n"
+  # @see https://sevgi.roktas.dev/derender/ Derender guide
   module Derender
-    # @!method self.decompile(content, id: nil)
-    #   Converts SVG/XML content into a derender node.
-    #   @param content [String] SVG/XML source content
-    #   @param id [String, nil] optional SVG id selecting a node inside the source
-    #   @return [Sevgi::Derender::Node] selected node in the derender tree
-    #   @raise [Sevgi::ArgumentError] when content is malformed or rootless, or when the id is absent
-    # @!method self.decompile_file(file, id: nil)
-    #   Converts an SVG/XML file into a derender node.
-    #   @param file [String] path to the source SVG/XML file
-    #   @param id [String, nil] optional SVG id selecting a node inside the source
-    #   @return [Sevgi::Derender::Node] selected node in the derender tree
-    #   @raise [Sevgi::ArgumentError] when the file cannot be found, file content is malformed or rootless, or the id is
-    #     absent
-    # @!method self.derender(content, id: nil)
-    #   Converts SVG/XML content into Sevgi DSL Ruby source.
-    #   @param content [String] SVG/XML source content
-    #   @param id [String, nil] optional SVG id selecting a node inside the source
-    #   @return [String] formatted Sevgi DSL source
-    #   @raise [Sevgi::ArgumentError] when content is malformed or rootless, or when the id is absent
-    #   @raise [Sevgi::PanicError] when generated Ruby source cannot be formatted
-    #   @note Namespace-aware dispatch preserves ordinary foreign/qualified nodes and nested SVG elements.
-    #   @note Unsafe bare Ruby names are emitted through the explicit `Element` DSL word.
-    # @!method self.derender_file(file, id: nil)
-    #   Converts an SVG/XML file into Sevgi DSL Ruby source.
-    #   @param file [String] path to the source SVG/XML file
-    #   @param id [String, nil] optional SVG id selecting a node inside the source
-    #   @return [String] formatted Sevgi DSL source
-    #   @raise [Sevgi::ArgumentError] when the file cannot be found, file content is malformed or rootless, or the id is
-    #     absent
-    #   @raise [Sevgi::PanicError] when generated Ruby source cannot be formatted
-    #   @note Namespace-aware dispatch preserves ordinary foreign/qualified nodes and nested SVG elements.
-    #   @note Unsafe bare Ruby names are emitted through the explicit `Element` DSL word.
-    # @!method self.evaluate(content, element, id: nil)
-    #   Evaluates SVG/XML content under a graphics element, including the selected node.
-    #   @param content [String] SVG/XML source content
-    #   @param element [Sevgi::Graphics::Element] target graphics element
-    #   @param id [String, nil] optional SVG id selecting a node inside the source
-    #   @return [Sevgi::Graphics::Element, nil] included selected/root graphics element, or nil when the selected node
-    #     produces no graphics output
-    #   @raise [Sevgi::ArgumentError] when content is malformed or rootless, or when the id is absent
-    #   @note Namespace-aware dispatch preserves ordinary foreign/qualified nodes and nested SVG elements.
-    # @!method self.evaluate_children(content, element, id: nil)
-    #   Evaluates only the selected node's children under a graphics element.
-    #   @param content [String] SVG/XML source content
-    #   @param element [Sevgi::Graphics::Element] target graphics element
-    #   @param id [String, nil] optional SVG id selecting a node inside the source
-    #   @return [Array<Sevgi::Graphics::Element>] included child graphics elements
-    #   @raise [Sevgi::ArgumentError] when content is malformed or rootless, or when the id is absent
-    #   @note Namespace-aware dispatch preserves ordinary foreign/qualified nodes and nested SVG elements.
-    # @!method self.evaluate_file(file, element, id: nil)
-    #   Evaluates an SVG/XML file under a graphics element, including the selected node.
-    #   @param file [String] path to the source SVG/XML file
-    #   @param element [Sevgi::Graphics::Element] target graphics element
-    #   @param id [String, nil] optional SVG id selecting a node inside the source
-    #   @return [Sevgi::Graphics::Element, nil] included selected/root graphics element, or nil when the selected node
-    #     produces no graphics output
-    #   @raise [Sevgi::ArgumentError] when the file cannot be found, file content is malformed or rootless, or the id is
-    #     absent
-    #   @note Namespace-aware dispatch preserves ordinary foreign/qualified nodes and nested SVG elements.
-    # @!method self.evaluate_file_children(file, element, id: nil)
-    #   Evaluates only the selected node's children from an SVG/XML file under a graphics element.
-    #   @param file [String] path to the source SVG/XML file
-    #   @param element [Sevgi::Graphics::Element] target graphics element
-    #   @param id [String, nil] optional SVG id selecting a node inside the source
-    #   @return [Array<Sevgi::Graphics::Element>] included child graphics elements
-    #   @raise [Sevgi::ArgumentError] when the file cannot be found, file content is malformed or rootless, or the id is
-    #     absent
-    #   @note Namespace-aware dispatch preserves ordinary foreign/qualified nodes and nested SVG elements.
+    private_constant :Attributes, :Document, :Elements
 
-    # Converts SVG/XML content into a derender node.
+    # Converts SVG/XML content into an immutable derender result.
     # @param content [String] SVG/XML source content
-    # @param id [String, nil] optional SVG id selecting a node inside the source
-    # @return [Sevgi::Derender::Node] selected node in the derender tree
+    # @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
+    #   subtree after id selection
+    # @return [Sevgi::Derender::Node] owned immutable selected node
     # @raise [Sevgi::ArgumentError] when content is malformed or rootless, or when the id is absent
-    def decompile(content, id: nil) = Document.new(content).decompile(id)
+    # @example Inspect a selected immutable node
+    #   root = Sevgi::Derender.decompile('<svg><g id="mark"><rect width="4"/></g></svg>')
+    #   mark = root.find("mark")
+    #   mark.name                  #=> "g"
+    #   mark.children.first.name  #=> "rect"
+    #   mark.attributes["id"]     #=> "mark"
+    # @see Sevgi::Derender.decompile_file
+    # @see Sevgi.Decompile
+    def self.decompile(content, id: nil, omit: nil) = Document.new(content).decompile(id, omit:)
 
-    # Converts an SVG/XML file into a derender node.
+    # Converts an SVG/XML file into an immutable derender result.
     # @param file [String] path to the source SVG/XML file
-    # @param id [String, nil] optional SVG id selecting a node inside the source
-    # @return [Sevgi::Derender::Node] selected node in the derender tree
+    # @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
+    #   subtree after id selection
+    # @return [Sevgi::Derender::Node] owned immutable selected node
     # @raise [Sevgi::ArgumentError] when the file cannot be found, file content is malformed or rootless, or the id is
     #   absent
-    def decompile_file(file, id: nil) = Document.load_file(file).decompile(id)
+    # @raise [SystemCallError] when the file cannot be read
+    # @see Sevgi::Derender.decompile
+    # @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.
     # @param content [String] SVG/XML source content
-    # @param id [String, nil] optional SVG id selecting a node inside the source
+    # @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
+    #   subtree after id selection
     # @return [String] formatted Sevgi DSL source
     # @raise [Sevgi::ArgumentError] when content is malformed or rootless, or when the id is absent
     # @raise [Sevgi::PanicError] when generated Ruby source cannot be formatted
     # @note Namespace-aware dispatch preserves ordinary foreign/qualified nodes and nested SVG elements.
     # @note Unsafe bare Ruby names are emitted through the explicit `Element` DSL word.
-    def derender(content, id: nil) = Document.new(content).decompile(id).derender
+    # @example Select first, then omit attributes from generated source
+    #   xml = '<svg><g id="mark" style="fill: red"><rect id="part"/></g></svg>'
+    #   Sevgi::Derender.derender(xml, id: :mark, omit: [:id, "style"])
+    #   #=> "g do\n  rect\nend\n"
+    # @see Sevgi::Derender.derender_file
+    # @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.
     # @param file [String] path to the source SVG/XML file
-    # @param id [String, nil] optional SVG id selecting a node inside the source
+    # @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
+    #   subtree after id selection
     # @return [String] formatted Sevgi DSL source
     # @raise [Sevgi::ArgumentError] when the file cannot be found, file content is malformed or rootless, or the id is
     #   absent
     # @raise [Sevgi::PanicError] when generated Ruby source cannot be formatted
+    # @raise [SystemCallError] when the file cannot be read
     # @note Namespace-aware dispatch preserves ordinary foreign/qualified nodes and nested SVG elements.
     # @note Unsafe bare Ruby names are emitted through the explicit `Element` DSL word.
-    def derender_file(file, id: nil) = Document.load_file(file).decompile(id).derender
+    # @see Sevgi::Derender.derender
+    # @see Sevgi.DerenderFile
+    def self.derender_file(file, id: nil, omit: nil) = Document.load_file(file).decompile(id, omit:).derender
 
     # Evaluates SVG/XML content under a graphics element, including the selected node.
     # @param content [String] SVG/XML source content
     # @param element [Sevgi::Graphics::Element] target graphics element
-    # @param id [String, nil] optional SVG id selecting a node inside the source
+    # @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
+    #   subtree after id selection
     # @return [Sevgi::Graphics::Element, nil] included selected/root graphics element, or nil when the selected node
     #   produces no graphics output
     # @raise [Sevgi::ArgumentError] when content is malformed or rootless, or when the id is absent
     # @note Namespace-aware dispatch preserves ordinary foreign/qualified nodes and nested SVG elements.
-    def evaluate(content, element, id: nil) = Document.new(content).decompile(id).evaluate(element)
+    # @example Include the selected node under an existing element
+    #   drawing = Sevgi::Graphics.SVG(:minimal)
+    #   included = Sevgi::Derender.evaluate('<circle id="mark" r="4"/>', drawing)
+    #   included.name   #=> :circle
+    #   included[:id]   #=> "mark"
+    # @see Sevgi::Derender.evaluate_file
+    # @see Sevgi.Evaluate
+    def self.evaluate(content, element, id: nil, omit: nil)
+      Document.new(content).decompile(id, omit:).evaluate(element)
+    end
 
     # Evaluates only the selected node's children under a graphics element.
     # @param content [String] SVG/XML source content
     # @param element [Sevgi::Graphics::Element] target graphics element
-    # @param id [String, nil] optional SVG id selecting a node inside the source
-    # @return [Array<Sevgi::Graphics::Element>] included child graphics elements
+    # @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
+    #   subtree after id selection
+    # @return [Array<Sevgi::Graphics::Element>] immutable included-child snapshot
     # @raise [Sevgi::ArgumentError] when content is malformed or rootless, or when the id is absent
     # @note Namespace-aware dispatch preserves ordinary foreign/qualified nodes and nested SVG elements.
-    def evaluate_children(content, element, id: nil) = Document.new(content).decompile(id).evaluate_children(element)
+    # @example Include only children and retain an immutable result snapshot
+    #   drawing = Sevgi::Graphics.SVG(:minimal)
+    #   children = Sevgi::Derender.evaluate_children('<g><rect/><circle/></g>', drawing)
+    #   children.map(&:name) #=> [:rect, :circle]
+    #   children.frozen?     #=> true
+    # @see Sevgi::Derender.evaluate_children_file
+    # @see Sevgi.EvaluateChildren
+    def self.evaluate_children(content, element, id: nil, omit: nil)
+      Document.new(content).decompile(id, omit:).evaluate_children(element)
+    end
 
     # Evaluates an SVG/XML file under a graphics element, including the selected node.
     # @param file [String] path to the source SVG/XML file
     # @param element [Sevgi::Graphics::Element] target graphics element
-    # @param id [String, nil] optional SVG id selecting a node inside the source
+    # @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
+    #   subtree after id selection
     # @return [Sevgi::Graphics::Element, nil] included selected/root graphics element, or nil when the selected node
     #   produces no graphics output
     # @raise [Sevgi::ArgumentError] when the file cannot be found, file content is malformed or rootless, or the id is
     #   absent
+    # @raise [SystemCallError] when the file cannot be read
     # @note Namespace-aware dispatch preserves ordinary foreign/qualified nodes and nested SVG elements.
-    def evaluate_file(file, element, id: nil) = Document.load_file(file).decompile(id).evaluate(element)
+    # @see Sevgi::Derender.evaluate
+    # @see Sevgi.EvaluateFile
+    def self.evaluate_file(file, element, id: nil, omit: nil)
+      Document.load_file(file).decompile(id, omit:).evaluate(element)
+    end
 
     # Evaluates only the selected node's children from an SVG/XML file under a graphics element.
     # @param file [String] path to the source SVG/XML file
     # @param element [Sevgi::Graphics::Element] target graphics element
-    # @param id [String, nil] optional SVG id selecting a node inside the source
-    # @return [Array<Sevgi::Graphics::Element>] included child graphics elements
+    # @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
+    #   subtree after id selection
+    # @return [Array<Sevgi::Graphics::Element>] immutable included-child snapshot
     # @raise [Sevgi::ArgumentError] when the file cannot be found, file content is malformed or rootless, or the id is
     #   absent
+    # @raise [SystemCallError] when the file cannot be read
     # @note Namespace-aware dispatch preserves ordinary foreign/qualified nodes and nested SVG elements.
-    def evaluate_file_children(file, element, id: nil)
-      Document.load_file(file).decompile(id).evaluate_children(element)
+    # @see Sevgi::Derender.evaluate_children
+    # @see Sevgi.EvaluateChildrenFile
+    def self.evaluate_children_file(file, element, id: nil, omit: nil)
+      Document.load_file(file).decompile(id, omit:).evaluate_children(element)
     end
-
-    extend self
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sevgi-derender
 version: !ruby/object:Gem::Version
-  version: 0.95.0
+  version: 0.98.2
 platform: ruby
 authors:
 - Recai Oktaş
@@ -15,28 +15,28 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.95.0
+        version: 0.98.2
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.95.0
+        version: 0.98.2
 - !ruby/object:Gem::Dependency
   name: sevgi-graphics
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.95.0
+        version: 0.98.2
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.95.0
+        version: 0.98.2
 - !ruby/object:Gem::Dependency
   name: css_parser
   requirement: !ruby/object:Gem::Requirement
@@ -79,7 +79,7 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.18'
-description: Takes an SVG input and converts it to a Sevgi script.
+description: Converts SVG or XML trees into Sevgi DSL source.
 email: roktas@gmail.com
 executables:
 - igves
@@ -126,7 +126,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.11
+rubygems_version: 4.0.16
 specification_version: 4
-summary: Convert SVG to Sevgi DSL.
+summary: SVG-to-Sevgi source conversion.
 test_files: []