sevgi-graphics 0.95.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d7f7d46384f89f99b807f703fdec7a4519d9504899fa6ad6e08133d4cf2cbba7
-  data.tar.gz: 74822aa3dbed9221c2caebd5d163d6c2ad96427a6957e73bbba19612d930070c
+  metadata.gz: 7965ed7aa4c5960cca6a4ed927258d13a5b5be7d9e327f4bf7da5b3480b66b1f
+  data.tar.gz: 88224f9179c50ceca0ae8e4ee7a92e5d8a6a0d2634ec3912356dc5e5d2d27053
 SHA512:
-  metadata.gz: baaeb127304fd553d7fb49f119d9179e4ff6023f24181d61f282faafdcebc0fb2174c7a076d8483044917a17987994e8fd87b60995be14354a6543ba40a1d302
-  data.tar.gz: 53101304229cde02e71911654b14b28cffb17d69ddd4d02afa1ae513abb4d999e28aedb3b28c76849c74f452a841ae9d2cf2c4204edf2e671cbec60bd33a8463
+  metadata.gz: 063d2529fc5869ef25f27ed44b927d28ae3ba6c48aca2365c0be78dbda65b895eb065b0c61ca960e66f955e0a8dbea8cc7b581ddf9ad4ec437c727e0541b9e43
+  data.tar.gz: fa1a68f7962e62bd991462e87bbbae0778321076af509ca2ede6b179a5eb1c133d707c3450d46688645ddf37050df49c63df608236fc1cfb3bcc811d20ff25a5

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 Graphics
 
-Core SVG DSL, document profiles, and rendering behavior.
+Sevgi Graphics implements the SVG DSL, document profiles, and rendering.
 
 ## Install
 
@@ -17,21 +17,24 @@ require "sevgi/graphics"
 ## Example
 
 ```ruby
-doc = Sevgi::Graphics.SVG(:minimal) { rect(width: 3, height: 5) }
-doc.call
+doc = Sevgi::Graphics.SVG(:minimal) { rect width: 3, height: 5 }
+puts doc.Render
 ```
 
+This focused gem exposes `Sevgi::Graphics.SVG` and lowercase component constructors. Install the umbrella `sevgi` gem
+when you need the global `SVG` facade or the `.sevgi` script runner.
+
 ## Ruby compatibility
 
-Requires Ruby 3.4.0 or newer. CI verifies 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.
+This gem needs only Ruby and its Ruby dependencies.
 
 ## Links
 
-- Documentation: https://sevgi.roktas.dev
-- API documentation: https://www.rubydoc.info/gems/sevgi-graphics
-- Source: https://github.com/roktas/sevgi/tree/main/graphics
-- Changelog: https://github.com/roktas/sevgi/blob/main/CHANGELOG.md
+- Documentation: <https://sevgi.roktas.dev>
+- API documentation: <https://www.rubydoc.info/gems/sevgi-graphics>
+- Source: <https://github.com/roktas/sevgi/tree/main/graphics>
+- Changelog: <https://github.com/roktas/sevgi/blob/main/CHANGELOG.md>

data/lib/sevgi/graphics/attribute.rb

@@ -4,11 +4,16 @@
 
 module Sevgi
   module Graphics
-    # Internal store syntax; not part of the SVG DSL command surface.
-    ATTRIBUTE_INTERNAL_PREFIX = "-"
-
-    # Attribute suffix that merges new values into an existing attribute.
-    ATTRIBUTE_UPDATE_SUFFIX = "+"
+    # Mutable facade for SVG attributes and non-rendering element metadata.
+    class Attributes
+      # Prefix marking supported non-rendering metadata names. Prefixed entries remain available through the facade but
+      # are omitted from SVG output.
+      META_PREFIX = "-"
+
+      # Suffix requesting an update of an existing value. String and Symbol values are space-joined, Arrays are
+      # concatenated, and Hashes are merged. When the attribute is absent, assignment uses normal replacement behavior.
+      UPDATE_SUFFIX = "+"
+    end
 
     # Attribute name normalization helpers.
     # @api private
@@ -20,7 +25,7 @@ module Sevgi
         # @param given [String, Symbol] attribute name
         # @return [Boolean]
         def internal?(given)
-          (@internal ||= {})[given] ||= key(given).start_with?(ATTRIBUTE_INTERNAL_PREFIX)
+          (@internal ||= {})[given] ||= key(given).start_with?(Attributes::META_PREFIX)
         end
 
         # Returns the normalized attribute id.
@@ -28,7 +33,7 @@ module Sevgi
         # @return [Symbol]
         def id(given)
           (@id ||= {})[given] ||= begin
-            name = updateable?(given) ? key(given).delete_suffix(ATTRIBUTE_UPDATE_SUFFIX) : key(given)
+            name = updateable?(given) ? key(given).delete_suffix(Attributes::UPDATE_SUFFIX) : key(given)
             XML.name(name, context: "XML attribute name") unless internal?(given)
             name.to_sym
           end
@@ -38,7 +43,7 @@ module Sevgi
         # @param given [String, Symbol] attribute name
         # @return [Boolean]
         def updateable?(given)
-          (@updateable ||= {})[given] ||= key(given).end_with?(ATTRIBUTE_UPDATE_SUFFIX)
+          (@updateable ||= {})[given] ||= key(given).end_with?(Attributes::UPDATE_SUFFIX)
         end
 
         private
@@ -55,6 +60,9 @@ module Sevgi
       # Owned mutable snapshots for values entering an attribute store.
       # @api private
       module Snapshot
+        SCALARS = [::NilClass, ::TrueClass, ::FalseClass, ::Symbol, ::Integer, ::Float, ::Rational, ::Complex].freeze
+        private_constant :SCALARS
+
         class << self
           def capture(value, normalize_keys: false, seen: {}.compare_by_identity)
             case value
@@ -85,12 +93,7 @@ module Sevgi
 
           def capture_value(value)
             text = XML.text(value, context: "XML attribute value")
-            case value
-            when ::Numeric, ::Symbol, ::NilClass, ::TrueClass, ::FalseClass
-              value
-            else
-              text
-            end
+            SCALARS.include?(value.class) ? value : text
           end
 
           def nested(value, seen)
@@ -125,6 +128,25 @@ module Sevgi
       # @api private
       def self.capture(value, normalize_keys: false) = Snapshot.capture(value, normalize_keys:)
 
+      # Returns normalized owned attributes with defaults for absent names.
+      # @param attributes [Hash] source attributes
+      # @param defaults [Hash] values inserted only when their normalized names are absent
+      # @return [Hash{Symbol => Object}] normalized owned attributes
+      # @raise [Sevgi::ArgumentError] when input contains an invalid, colliding, or unsupported attribute
+      # @api private
+      def self.defaults(attributes, **defaults)
+        attributes = Attributes.new(attributes)
+        defaults.each { |name, value| attributes[name] = value unless attributes.has?(name) }
+        attributes.to_h
+      end
+
+      # Returns normalized owned attributes.
+      # @param attributes [Hash] source attributes
+      # @return [Hash{Symbol => Object}] normalized owned attributes
+      # @raise [Sevgi::ArgumentError] when input contains an invalid, colliding, or unsupported attribute
+      # @api private
+      def self.normalize(attributes) = Attributes.new(attributes).to_h
+
       # Returns the text form used for an XML attribute value before escaping.
       # @param value [Object] attribute value
       # @return [String]
@@ -144,10 +166,11 @@ module Sevgi
         XML.text(text, context: "XML attribute value")
       end
 
-      # Mutable SVG attribute store with Sevgi update syntax.
+      # Mutable backing store for SVG attributes.
+      # @api private
       class Store
         # Creates an attribute store from recursively owned snapshots. Mutable non-container leaves are stringified
-        # once; later caller mutation cannot change the store.
+        # once. Later caller mutation cannot change the store.
         # @param attributes [Hash] initial attributes
         # @return [void]
         # @raise [Sevgi::ArgumentError] when input is not a Hash or a name/value is invalid, cyclic, colliding, or cannot
@@ -164,22 +187,13 @@ module Sevgi
         # @raise [Sevgi::ArgumentError] when input is not a Hash or a name/value is invalid, cyclic, colliding, or cannot
         #   be converted
         def import(attributes)
-          ArgumentError.("Attributes must be imported from a Hash") unless attributes.is_a?(::Hash)
-
-          hash = attributes.each_with_object({}) do |(key, value), captured|
-            next if value.nil?
-
-            id = Attribute.id(key)
-            ArgumentError.("Attribute names collide after normalization: #{id}") if captured.key?(id)
-
-            captured[id] = Attribute.capture(value, normalize_keys: value.is_a?(::Hash))
-          end
+          updated = @store.dup
+          entries(attributes).each { |entry| assign(updated, *entry) }
 
-          @store.merge!(hash)
+          @store.replace(updated)
         end
 
-        # Returns a live stored attribute value. Mutating a returned container intentionally mutates this store; rendering
-        # revalidates the resulting value.
+        # Returns a stored attribute value for the public facade.
         # @param key [String, Symbol] attribute key
         # @return [Object, nil]
         # @raise [Sevgi::ArgumentError] when key is not a valid XML attribute name
@@ -189,7 +203,7 @@ module Sevgi
 
         # Assigns a recursively owned attribute snapshot. Mutable non-container leaves are stringified once.
         # @param key [String, Symbol] attribute key
-        # @param value [Object, nil] attribute value; nil is ignored
+        # @param value [Object, nil] attribute value. Nil is ignored
         # @return [Object, nil] stored snapshot or nil
         # @raise [Sevgi::ArgumentError] when update syntax receives incompatible values
         # @raise [Sevgi::ArgumentError] when update syntax receives an unsupported value type
@@ -199,7 +213,7 @@ module Sevgi
 
           id = Attribute.id(key)
           value = Attribute.capture(value, normalize_keys: value.is_a?(::Hash))
-          @store[id] = @store.key?(id) && Attribute.updateable?(key) ? update(id, value) : value
+          @store[id] = @store.key?(id) && Attribute.updateable?(key) ? update(@store[id], value) : value
         end
 
         # Deletes an attribute by normalized key.
@@ -210,13 +224,13 @@ module Sevgi
           @store.delete(Attribute.id(key))
         end
 
-        # Returns public attributes ready for rendering. Nested values remain live store values.
+        # Returns rendering attributes, excluding non-rendering metadata. Nested values remain live store values.
         # @return [Hash] shallow attribute view
         def export
           hash = @store.reject { |id, _| Attribute.internal?(id) }
           return hash unless hash.key?(:id)
 
-          # A small aesthetic touch: always keep the id attribute first
+          # Keep id first for stable, readable SVG output.
           {id: hash.delete(:id), **hash}
         end
 
@@ -229,9 +243,8 @@ module Sevgi
         end
 
         # Copies the attribute store with recursively independent values.
-        # @param original [Sevgi::Graphics::Attribute::Store] store to copy
+        # @param original [Sevgi::Graphics::Attributes] store to copy
         # @return [void]
-        # @raise [Sevgi::ArgumentError] when live stored values became cyclic or invalid
         def initialize_copy(original)
           @store = {}
           original.store.each { |key, value| @store[key] = Attribute.capture(value) }
@@ -239,15 +252,14 @@ module Sevgi
           super
         end
 
-        # Returns public attribute names.
+        # Returns rendering attribute names, excluding non-rendering metadata.
         # @return [Array<Symbol>]
         def list
           export.keys
         end
 
-        # Returns the live internal attribute Hash. Mutating it intentionally mutates this store; rendering revalidates
-        # names and values.
-        # @return [Hash] live internal store
+        # Returns the internal attribute and metadata Hash.
+        # @return [Hash] backing store
         def to_h
           @store
         end
@@ -268,12 +280,32 @@ module Sevgi
         UPDATER = {
           ::String => proc { |old_value, new_value| [old_value, new_value].reject(&:empty?).join(" ") },
           ::Symbol => proc { |old_value, new_value| [old_value, new_value].reject(&:empty?).join(" ").to_sym },
-          ::Array => proc { |old_value, new_value| [old_value, new_value] },
-          ::Hash => proc { |old_value, new_value| old_value.merge(new_value.transform_keys(&:to_sym)) }
+          ::Array => proc { |old_value, new_value| old_value + new_value },
+          ::Hash => proc { |old_value, new_value| old_value.merge(new_value) }
         }.freeze
 
-        def update(id, new_value)
-          (old_value = @store[id]).nil? ? new_value : UPDATER[new_value.class].call(*sanitized(old_value, new_value))
+        def assign(store, key, id, value)
+          store[id] = store.key?(id) && Attribute.updateable?(key) ? update(store[id], value) : value
+        end
+
+        def entries(attributes)
+          ArgumentError.("Attributes must be imported from a Hash") unless attributes.is_a?(::Hash)
+
+          identities = {}
+          attributes.filter_map do |key, value|
+            next if value.nil?
+
+            id = Attribute.id(key)
+            ArgumentError.("Attribute names collide after normalization: #{id}") if identities.key?(id)
+
+            identities[id] = true
+            value = Attribute.capture(value, normalize_keys: value.is_a?(::Hash))
+            [key, id, value]
+          end
+        end
+
+        def update(old_value, new_value)
+          UPDATER[new_value.class].call(*sanitized(old_value, new_value))
         end
 
         def sanitized(old_value, new_value)
@@ -292,7 +324,96 @@ module Sevgi
       end
     end
 
-    # Public alias for the SVG attribute store.
-    Attributes = Attribute::Store
+    # Names beginning with {META_PREFIX} can be read, assigned, deleted, merged, and copied like ordinary
+    # attributes. They appear in {#to_h}, but public SVG attribute enumeration and rendered XML omit them. All values
+    # entering or leaving this facade are recursively owned snapshots. Appending {UPDATE_SUFFIX} to a name requests a
+    # same-family update: Strings and Symbols are space-joined, Arrays are concatenated, and Hashes are merged. An update
+    # to an absent name behaves as replacement, and nil assignments are ignored.
+    #
+    # @example Inspect and update element attributes
+    #   element = Sevgi::Graphics.SVG { rect id: "copy", "-source": "original" }.children.first
+    #   element.attributes[:"-source"] # => "original"
+    #   element.attributes.merge!(fill: "red")
+    #   element.attributes.to_h # => { id: "copy", :"-source" => "original", fill: "red" }
+    class Attributes
+      # Creates an attribute facade from recursively owned snapshots.
+      # @param attributes [Hash] initial attributes and non-rendering metadata
+      # @return [void]
+      # @raise [Sevgi::ArgumentError] when input is not a Hash or contains an invalid name or value
+      def initialize(attributes = {})
+        @store = Attribute::Store.new(attributes)
+      end
+
+      # Returns an owned snapshot of an attribute value.
+      # @param key [String, Symbol] attribute key
+      # @return [Object, nil] recursively owned value or nil when absent
+      # @raise [Sevgi::ArgumentError] when key is not a valid attribute name
+      def [](key) = snapshot(@store[key])
+
+      # Assigns or updates a recursively owned attribute value.
+      # @param key [String, Symbol] attribute key, optionally ending in {UPDATE_SUFFIX}
+      # @param value [Object, nil] attribute value. Nil is ignored
+      # @return [Object, nil] recursively owned resulting value or nil when absent
+      # @raise [Sevgi::ArgumentError] when the name or value is invalid, or an existing update uses incompatible or
+      #   unsupported value families
+      def []=(key, value)
+        @store[key] = value
+        snapshot(@store[key])
+      end
+
+      # Deletes an attribute and returns an owned snapshot of its value.
+      # @param key [String, Symbol] attribute key
+      # @return [Object, nil] deleted value or nil when absent
+      # @raise [Sevgi::ArgumentError] when key is not a valid attribute name
+      def delete(key) = snapshot(@store.delete(key))
+
+      # Reports whether an attribute exists.
+      # @param key [String, Symbol] attribute key
+      # @return [Boolean]
+      # @raise [Sevgi::ArgumentError] when key is not a valid attribute name
+      def has?(key) = @store.has?(key)
+
+      # Copies the facade with recursively independent values.
+      # @param original [Sevgi::Graphics::Attributes] facade to copy
+      # @return [void]
+      # @raise [Sevgi::ArgumentError] when stored values became invalid
+      # @api private
+      def initialize_copy(original)
+        super
+        @store = original.store.dup
+      end
+
+      private :initialize_copy
+
+      # Returns rendering attribute names, excluding non-rendering metadata.
+      # @return [Array<Symbol>] frozen name snapshot
+      def keys = @store.list.freeze
+
+      # Atomically assigns or updates recursively owned attributes.
+      # @param attributes [Hash] attributes and non-rendering metadata. Names can end in {UPDATE_SUFFIX}
+      # @return [Sevgi::Graphics::Attributes] self
+      # @raise [Sevgi::ArgumentError] when input is not a Hash, names collide, a name or value is invalid, or an existing
+      #   update uses incompatible or unsupported value families
+      def merge!(attributes)
+        @store.import(attributes)
+        self
+      end
+
+      # Returns a recursively owned Hash snapshot including non-rendering metadata.
+      # @return [Hash{Symbol => Object}] owned attribute and metadata snapshot
+      def to_h = snapshot(@store.to_h)
+
+      private
+
+      def snapshot(value) = Attribute.capture(value)
+
+      def xml_lines = @store.to_xml_lines
+
+      protected
+
+      attr_reader :store
+    end
+
+    private_constant :Attribute
   end
 end