sevgi-derender 0.95.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 84e2eb700b9e867ffb80ad1223ba2bfaf32f632b19d05a07db71191a8a611cac
-  data.tar.gz: 7cefed91f1645a9c195dd65d677f7c9cb041f6f4f4093b90aae2aa56a848342b
+  metadata.gz: e02ddd4869fac0f3ab35c12f53bcdd9e23bdc936d8753a17ff56b651c8a07882
+  data.tar.gz: aeff138c2ced508eca978c9eccd2e547c808e2be7d4d7bac859a57700e118892
 SHA512:
-  metadata.gz: fa91f3c9a83fa0b8a6edfa104131e8fcd533421bd182818713c3235c046b431926a031d2a3b52803afb4150f1757ace6b50f42977ef6065b39cbb3ea2f5bad94
-  data.tar.gz: da2e1ce83ee737df97b9dd01b80abb2d372f2315eab3e6051b1cb563120185afd7f326b158f869760cdc71c623a1bd9e12b2dd82c05c056ced7b0e469ea78b42
+  metadata.gz: dee05c8a84e8872ce946aa18f3f10071c0b07bea43170cc3a59f03ef9b434383e184478c84fe43270bf9524af3b135ee827bbe55868a64b62099af8dc34f37a1
+  data.tar.gz: db4b7b23ca99f153f40ff0ec6bc2cdd126c399a466b93c3d92f028669a672de39e9dc783f093f1bb68fa1b738b7809fc6693651c19e251700248e9601afdb581

data/CHANGELOG.md

@@ -3,7 +3,226 @@
 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
+
+### 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
 
@@ -87,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

@@ -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
 
@@ -18,27 +18,55 @@ 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>'
+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
-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 can use platform packages on some Ruby platforms.
 
 ## 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,16 +82,16 @@ 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
         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}") }
@@ -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)
@@ -117,7 +142,7 @@ module Sevgi
       rescue ::StandardError => e
         raise if raw_error?(options)
 
-        die(e, file)
+        die(e)
       end
 
       def raw_error?(options)
@@ -125,4 +150,6 @@ module Sevgi
       end
     end
   end
+
+  private_constant :Binaries
 end

data/lib/sevgi/derender/attributes.rb

@@ -35,11 +35,14 @@ module Sevgi
 
         {**pre, **hash, **post}
           .map do |key, value|
-            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,13 +14,13 @@ 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"))
 
         ArgumentError.("File not found: #{path}") unless ::File.exist?(entry)
 
-        content = ::File.read(entry)
+        content = ::File.binread(entry)
         new(content)
       end
 
@@ -29,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
 
@@ -37,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
 
@@ -61,31 +68,30 @@ 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.
-      # @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")
-          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.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
-      # 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|
@@ -97,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
@@ -109,6 +128,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