glyphs 0.2.3 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8c8e883474d143ec14502ef27013e1a264c0a89d76b7dd24ef29d2025d96ad5c
-  data.tar.gz: afad4dcca3bda0162be398c66a7a7bb65c36af8facb9c4b5eb13f5d4d29a1d2c
+  metadata.gz: eb4ffc81dcfd96faf6a0f23e3f57780340db27348666e520c7bbc747af04065e
+  data.tar.gz: 48e331ff55405e3c054fd0464a50a38ccf75df6d3e837e2a0edf3e3a18894de8
 SHA512:
-  metadata.gz: a9c94ace100a67479cb24e793dfd7bc9c71238bfd472f2d29be37076410c27e0cc69d48b2952fad4574bac1e5184770d0b19542284c06edb520fece72d6c1526
-  data.tar.gz: 8d2cb2a5ca53b92884b28de6a2813326796b034754d5b6f14ab37b4fb7f54c1d49b6deb61dc53d75c0c668e8908447e9a5fdfd8bb71fbb5440c22a5bd9c15b61
+  metadata.gz: 382ddd08e2e3cd53ce5164bbb6104bfc46b2c1caf48ac5d39b24e08f3a7594cbd0fa95424793d746c616bc7e4e8621ded6c0af1c5bf4357fa309ded75c49c79a
+  data.tar.gz: 1205d90f3d975f3a0880e3768d68c0daf12664c98efb01f715296fd1230dd24fb2af4981e74bd689f98ddf3b7b962c29dc7e3e4dd0125024c49944b312ba8995

data/CHANGELOG.md

@@ -1,6 +1,111 @@
 # Changelog
 
-## [Unreleased]
+## [0.3.0]
+
+### Changed
+
+- **The configuration is frozen once a Rails app has booted.** `Glyphs::Railtie`
+  calls `Glyphs.finalize!` from `after_initialize`, after every
+  `config/initializers` file; no application code is needed. Writing to it
+  after that raises `FrozenError`: `Glyphs.configure` in an app's own
+  `config.after_initialize` block (it runs after glyphs' hook) or
+  `Glyphs.configuration.<setting> =` at runtime. Configure glyphs in an
+  initializer; in tests, `Glyphs.reset_configuration!` starts over with a
+  fresh, writable configuration. Outside Rails nothing is frozen until you call
+  `Glyphs.finalize!`. Refs #25
+
+- **perf: `svg_for` per call, measured with `bench/svg_for.rb`** (Ruby 4.0.6,
+  YJIT, arm64 macOS, before → after, same machine, interleaved runs):
+
+  | case | before | after | allocations |
+  |---|---|---|---|
+  | cache hit, no attributes | 0.51-0.53 µs | 0.67 µs | 2 → 3 |
+  | cache hit, same `class:` | 0.65-0.77 µs | 2.25-2.30 µs | 2 → 15 |
+  | distinct `id:` per call | 113-188 µs (a miss every call, cache growing) | 3.3-3.5 µs | 302 → 22 |
+  | `cache_svgs = false` | 86-129 µs | unchanged | 297 |
+
+  A repeated identical render is about 1.6 µs slower per icon (the attributes
+  are now merged on every call); renders with varying attributes are 30× or more
+  faster and the cache's memory is bounded. Per icon, not per request. `svg_for`
+  without attributes returns the cached markup, frozen. Refs #25
+
+### Fixed
+
+- **fix: the SVG cache no longer grows without bound.** It was keyed on
+  `[library, variant, name, attributes]`, so a dynamic `class:` or `id:` per
+  render added an entry per call, for the life of the process: a memory leak on
+  any busy page. It is now a bounded LRU (`config.svg_cache_size`, 1024 by
+  default) keyed on `[library, variant, name]`; each call's attributes are
+  applied to the cached markup in plain Ruby, byte-identical to the icons gem's
+  own render (HTML boolean attributes, `href`/`src`/`action` and control
+  characters, which libxml2 writes specially, render through the icons gem,
+  uncached). Refs #25
+
+- **fix: `Glyphs.register_library` and `Glyphs.configure` are serialized.**
+  `register_library` was an unguarded `const_defined?`/`const_set`, so threads
+  registering the same library at once could each define the constant and get
+  different classes back. Both now run under one module lock (a Monitor, so a
+  `configure` block may register a library). The configuration is created at
+  load instead of on first read. Refs #25
+
+- **fix: `Glyphs/IconResolution`'s class-level memos are locked.** The
+  icon-directory cache and the warn-once set were lazily built class instance
+  variables; they are now read and written under a Mutex. Refs #25
+
+### Added
+
+- **`Glyphs.finalize!`**: freezes the configuration and makes every setting
+  Ractor-shareable that can be, so `svg_for` can read it from a non-main
+  Ractor. Called for you in a Rails app (above); outside Rails, call it at the
+  end of boot. It never raises and never freezes an object of the app's: a
+  collection setting or a Proc becomes a shareable copy, and a value that
+  cannot be shared, such as the README's `on_missing_icon` lambda (it closes
+  over the initializer's `self`) or a callable holding a logger, is kept as
+  is. The configuration is then readable on the main Ractor only; reading it
+  from another Ractor raises `Ractor::IsolationError` until `on_missing_icon`
+  is a Ractor-shareable callable (frozen, with nothing unshareable inside) or a
+  `Ractor.shareable_proc` (Ruby 4.0+). The SVG cache is per Ractor;
+  `Glyphs.preload_svg` seeds a Ractor's cache with markup rendered on the main
+  Ractor, since the icons gem cannot render inside another one. It serves calls
+  without `data:` whose attributes the cache can apply. Refs #25
+
+- **`config.svg_cache_size`** (default 1024; anything but a positive Integer
+  raises `ArgumentError`), and `Glyphs.svg_cache`, the current Ractor's cache.
+  Refs #25
+
+## [0.2.4] - 2026-07-25
+
+### Fixed
+
+- **`Glyphs/IconResolution` no longer fails open on a missing icon directory.**
+  A directory that did not exist produced the same empty list as one that
+  existed with no SVGs, and both were read as "nothing to check" — so a library
+  that was never synced, or a `DefaultVariant` naming a variant the project does
+  not have, silently disabled the cop for every call site of that library. Green
+  cop, green CI, no validation at all, indefinitely. `load_icons` now returns
+  `nil` for an absent directory and `[]` for an empty one; the absent case warns
+  once per library/variant, naming the path. The synced-but-empty case still
+  passes silently. Refs #8
+
+- **Cop options are declared, so RuboCop stops calling them unsupported.**
+  `config/default.yml` documented `Libraries` (`Glyphs/IconResolution`) and
+  `Mappings` (`Glyphs/LegacyIconHelper`) only in comments, and never mentioned
+  `LibraryComponents` (`Glyphs/LegacyIconHelper`, `Glyphs/PreferLibraryComponent`)
+  at all. RuboCop derives its supported-parameter list from the keys actually
+  present in that file, so it warned `does not support <param> parameter` on
+  every run — for four working options, one of which
+  `Glyphs/LegacyIconHelper` itself tells you to add. Each is now declared with an
+  empty default (a no-op merge), so the options are validated instead of
+  reported, with behaviour unchanged. Refs #7
+
+### Added
+
+- **`Glyphs/IconResolution` gained a `Strict` option** (default `false`). It
+  escalates the missing-icon-directory warning above to an offence, so projects
+  that depend on this cop can fail closed in CI instead of trusting a warning
+  not to scroll past.
+
+## [0.2.3] - 2026-07-17
 
 ### Fixed
 
@@ -11,6 +116,8 @@
   `glyphs:prune_icons`. `collect_declaration` now unwraps zero-arg `.freeze`
   (and parentheses) before walking the value.
 
+## [0.2.2] - 2026-07-11
+
 ### Added
 
 - **Dynamic icon calls are now resolved from source.** `SourceScanner` no longer
@@ -23,7 +130,7 @@
     pair keyed `/icon/i`, or a constant named `/ICON/`) are kept for every
     dynamically-rendered library, closing the cross-file gap (e.g. a notifier
     `ICON = :bell` constant rendered from a view). Frozen maps
-    (`ICONS = { … }.freeze`) are included — see Fixed above.
+    (`ICONS = { … }.freeze`) are included since 0.2.3.
 
   This makes `keep_icons` a last-resort escape hatch (DB/ENV/gem-chrome names)
   rather than the primary mechanism. Only literals are harvested, so the scanner

data/README.md

@@ -96,13 +96,51 @@ Glyphs.configure do |config|
     heroicons: "question-mark-circle"
   }
 
-  # Memoize rendered SVG strings per [library, variant, name, attributes]. Default: true.
+  # Memoize rendered SVGs per [library, variant, name] and whether data: is given;
+  # the call's attributes (class:, data:, ...) are applied to the cached markup
+  # each time. Attributes the icons gem writes specially (HTML boolean attributes,
+  # href/src/action, control characters) render uncached. Default: true.
   # Note: fallback renders are cached under the original name, so on_missing_icon
-  # fires once per process per missing icon rather than on every render.
+  # fires once per cache entry (with and without data:) while it stays cached, and
+  # on every render that goes uncached.
   config.cache_svgs = true
+
+  # How many icons the cache holds (least recently used evicted first). One
+  # cache per Ractor, so a plain threaded server has one. Default: 1024.
+  config.svg_cache_size = 1024
 end
 ```
 
+## Ractors
+
+In a Rails app glyphs finalizes its configuration once the app has booted (`after_initialize`, after every
+`config/initializers` file), with no code of yours: the configuration is frozen and every setting that can be
+is made Ractor-shareable, so `svg_for` can read it from any Ractor. Outside Rails, call `Glyphs.finalize!`
+once at the end of boot, after every `Glyphs.configure`.
+
+From then on the configuration is read-only, and writing to it raises `FrozenError`. Configure glyphs in an
+initializer, not in a `config.after_initialize` block of your own (that runs after glyphs' hook). In tests,
+`Glyphs.reset_configuration!` starts over with a fresh, writable configuration.
+
+Finalizing never raises and never freezes an object of yours: a collection setting or a Proc becomes a
+shareable copy, and a value that cannot be shared is kept as is. `on_missing_icon` is the usual one: a lambda that closes over the
+initializer's `self` (like the one above) or a callable holding a logger. The configuration then stays
+readable on the main Ractor only, which is all an app without Ractors needs; another Ractor reading it raises
+`Ractor::IsolationError`. To use glyphs from other Ractors, give `on_missing_icon` a Ractor-shareable value: an
+object with a `#call` method that `Ractor.shareable?` accepts (frozen, with nothing unshareable inside) or
+`Ractor.shareable_proc` (Ruby 4.0+).
+
+The icons gem cannot render inside a non-main Ractor today (its configuration is unshareable module
+state, and Nokogiri is Ractor-unsafe), so each Ractor's cache starts empty and a miss there raises.
+Render on the main Ractor and hand the markup over with `Glyphs.preload_svg`; cache hits then work in that
+Ractor for calls without `data:` whose attributes the cache can apply (a `data:` call, or one with an attribute
+that renders uncached, still needs the icons gem):
+
+```ruby
+svg = Glyphs.svg_for(name: "house", library: :lucide, variant: nil, attributes: {}) # main Ractor
+Glyphs.preload_svg(name: "house", library: :lucide, svg:)                           # in the Ractor
+```
+
 ## Shrinking icons in Docker
 
 `rails g rails_icons:sync` copies a library's **entire** icon set into
@@ -210,6 +248,10 @@ Glyphs/LegacyIconHelper:
   # Mappings replaces the built-in defaults (_lucide/_phosphor/_hero/_heroicon/_tabler):
   # Mappings:
   #   _custom: CustomIcon
+  # LibraryComponents merges over the built-in library => component map, so
+  # `icon("x", library: "customlib")` corrects to `CustomIcon("x")`:
+  # LibraryComponents:
+  #   customlib: CustomIcon
 ```
 
 ### Glyphs/IconResolution
@@ -231,14 +273,38 @@ Glyphs/IconResolution:
   # Libraries merges over the built-in defaults (component => Dir/DefaultVariant):
   Libraries:
     PhosphorIcon: { Dir: phosphor, DefaultVariant: regular }
+  # Escalate a missing icon directory from a warning to an offence:
+  Strict: false
 ```
 
+If the directory a library resolves to does not exist — the library was never synced, or
+`DefaultVariant` names a variant you do not have — the cop cannot validate any of that
+library's call sites. Rather than pass silently, it warns once per library/variant:
+
+```
+[Glyphs/IconResolution] Icon directory `app/assets/svg/icons/phosphor/regular` not found,
+so `PhosphorIcon` names are not validated. Sync the library or fix `IconsPath`/`Libraries`.
+```
+
+Set `Strict: true` to make that an offence instead, so CI fails closed rather than reporting
+green while checking nothing. A directory that exists but ships no SVGs is not a
+misconfiguration and stays silent either way.
+
 ### Glyphs/PreferLibraryComponent
 
 ```ruby
 Icon(:house, library: :lucide) # => LucideIcon(:house)
 ```
 
+```yaml
+Glyphs/PreferLibraryComponent:
+  Include:
+    - app/**/*.rb
+  # LibraryComponents merges over the built-in library => component map:
+  # LibraryComponents:
+  #   customlib: CustomIcon
+```
+
 ## Migrating an app off icon helpers
 
 1. Add `gem "glyphs"`, `include Glyphs` where the helpers used to be included.

data/config/default.yml

@@ -3,10 +3,13 @@ Glyphs/LegacyIconHelper:
   Enabled: true
   VersionAdded: '0.1.0'
   SafeAutoCorrect: true
-  # Mappings replaces the built-in defaults when set:
-  # Mappings:
+  # Replaces the built-in helper => component defaults when set, e.g.
   #   _lucide: LucideIcon
   #   _heroicon: HeroIcon
+  Mappings: {}
+  # Merges over the built-in library => component map, e.g.
+  #   customlib: CustomIcon
+  LibraryComponents: {}
   DefaultLibraryComponent: HeroIcon
 
 Glyphs/IconResolution:
@@ -14,12 +17,18 @@ Glyphs/IconResolution:
   Enabled: true
   VersionAdded: '0.1.0'
   IconsPath: app/assets/svg/icons
-  # Libraries merges over the built-in defaults:
-  # Libraries:
+  # Merges over the built-in component => directory/variant defaults, e.g.
   #   PhosphorIcon: { Dir: phosphor, DefaultVariant: light }
+  Libraries: {}
+  # An icon directory that does not exist warns once per library/variant.
+  # Strict turns that warning into an offence so CI fails closed.
+  Strict: false
 
 Glyphs/PreferLibraryComponent:
   Description: 'Prefer library-specific components over generic Icon(..., library: ...).'
   Enabled: true
   VersionAdded: '0.1.0'
   SafeAutoCorrect: true
+  # Merges over the built-in library => component map, e.g.
+  #   customlib: CustomIcon
+  LibraryComponents: {}

data/lib/glyphs/configuration.rb

@@ -8,12 +8,16 @@ module Glyphs
       heroicons: "question-mark-circle"
     }.freeze
 
+    DEFAULT_SVG_CACHE_SIZE = 1024
+
     # raise_on_missing: boolean; when true, Icons::IconNotFound is re-raised.
     #   Defaults to true in local Rails environments (and outside Rails).
     # on_missing_icon: optional callable(error, name:, library:, variant:),
     #   invoked before the fallback renders when not raising.
     # fallback_icons: { library => icon_name } rendered instead of a missing icon.
-    # cache_svgs: memoize rendered SVG strings per [library, variant, name, attributes].
+    # cache_svgs: memoize rendered SVGs per [library, variant, name]; the
+    #   caller's attributes are applied to the cached markup on every call.
+    # svg_cache_size: how many icons each Ractor's LRU cache holds (1024).
     # keep_icons: icons the pruner must keep despite no static reference
     #   (dynamic / data-driven names). A flat list of names/globs, or a
     #   { library => [names/globs] } hash. fallback_icons are always kept.
@@ -22,14 +26,54 @@ module Glyphs
     #   names icons. Never replaces the defaults (nil = defaults only).
     attr_accessor :raise_on_missing, :on_missing_icon, :fallback_icons, :cache_svgs,
       :keep_icons, :prune_source_globs
+    attr_reader :svg_cache_size
 
     def initialize
       @raise_on_missing = defined?(Rails) ? Rails.env.local? : true
       @on_missing_icon = nil
       @fallback_icons = DEFAULT_FALLBACK_ICONS.dup
       @cache_svgs = true
+      @svg_cache_size = DEFAULT_SVG_CACHE_SIZE
       @keep_icons = []
       @prune_source_globs = nil
     end
+
+    def svg_cache_size=(size)
+      unless size.is_a?(Integer) && size.positive?
+        raise ArgumentError, "svg_cache_size must be a positive Integer, got #{size.inspect}"
+      end
+
+      @svg_cache_size = size
+    end
+
+    # Freezes the configuration and makes every setting Ractor-shareable that
+    # can be, so svg_for can read it from a non-main Ractor. Glyphs.finalize!
+    # calls it (in a Rails app, Glyphs::Railtie does after boot). Never raises
+    # and never freezes an object the app still holds: a collection or a Proc
+    # becomes a shareable copy, and a value that cannot be shared (an
+    # on_missing_icon lambda closing over self, a callable holding a logger) is
+    # kept as is, which leaves the configuration readable on the main Ractor only.
+    def finalize!
+      return self if frozen?
+
+      if defined?(::Ractor)
+        instance_variables.each { |ivar| instance_variable_set(ivar, shareable(instance_variable_get(ivar))) }
+      end
+      freeze
+    end
+
+    private
+
+    def shareable(value)
+      return value if ::Ractor.shareable?(value)
+
+      case value
+      when ::Proc then ::Ractor.make_shareable(value.dup) # Ractor's copy: cannot copy a Proc; #dup can
+      when ::Hash, ::Array, ::String then ::Ractor.make_shareable(value, copy: true)
+      else value # an app's object: freezing it in place would freeze what it refers to (its logger) too
+      end
+    rescue StandardError # Ractor::Error, or TypeError/ArgumentError for what cannot be copied or shared
+      value
+    end
   end
 end

data/lib/glyphs/icon_reference.rb

@@ -11,7 +11,7 @@ module Glyphs
   # The library/variant tables are sourced from the `icons` gem wherever
   # possible (`default_variant_for`) so they never drift from what actually
   # resolves at render time.
-  class IconReference < Data.define(:library, :variant, :name) # rubocop:disable Style/DataInheritance
+  class IconReference < Data.define(:library, :variant, :name)
     # Subclassed (not the block form) so the constants below are namespaced under
     # IconReference — constants defined inside a `Data.define do…end` block leak
     # to the enclosing scope instead of nesting under the class.
@@ -44,13 +44,16 @@ module Glyphs
       "_tabler" => :tabler
     }.freeze
 
+    # Component name (`"LucideIcon"`) => library symbol (`:lucide`). Built at
+    # load, frozen, so it is shareable and never lazily (re)computed.
+    COMPONENT_TO_LIBRARY = LIBRARY_TO_COMPONENT.to_h { |library, component| [component, library] }.freeze
+
     # Raw `iconify lucide--house` class strings.
     ICONIFY_PATTERN = /\biconify\s+(lucide|phosphor|heroicons)--([a-z0-9-]+)/
 
     class << self
-      # Component name (`"LucideIcon"`) => library symbol (`:lucide`).
       def component_to_library
-        @component_to_library ||= LIBRARY_TO_COMPONENT.to_h { |library, component| [component, library] }.freeze
+        COMPONENT_TO_LIBRARY
       end
 
       def legacy_helpers
@@ -61,7 +64,7 @@ module Glyphs
       # symbol, or nil when the method isn't an icon call.
       def library_for(method_name)
         name = method_name.to_s
-        component_to_library[name] || LEGACY_HELPERS[name]
+        COMPONENT_TO_LIBRARY[name] || LEGACY_HELPERS[name]
       end
 
       # The library's default variant, as configured in the icons gem. Returns a

data/lib/glyphs/railtie.rb

@@ -1,12 +1,20 @@
 # frozen_string_literal: true
 
 module Glyphs
-  # Loaded only when Rails is present (see the guard in lib/glyphs.rb). Its sole
-  # job is to expose the icon-pruning rake task to consuming apps. Kept a
-  # Railtie, not an Engine: glyphs contributes no routes, views, or migrations.
+  # Loaded only when Rails is present (see the guard in lib/glyphs.rb). It
+  # exposes the icon-pruning rake task to consuming apps and finalizes the
+  # configuration after boot. Kept a Railtie, not an Engine: glyphs contributes
+  # no routes, views, or migrations.
   class Railtie < ::Rails::Railtie
     rake_tasks do
       load File.expand_path("../tasks/glyphs.rake", __dir__)
     end
+
+    # Once every initializer has run (and so every Glyphs.configure), freeze the
+    # configuration for Ractors, with no code of the app's. This is the hook
+    # config.after_initialize registers (Rails::Railtie::Configuration#after_initialize);
+    # calling it directly keeps the Railtie from being instantiated at require
+    # (Glyphs::Railtie.@instance), which Rails otherwise does only at boot.
+    ActiveSupport.on_load(:after_initialize, yield: true) { Glyphs.finalize! }
   end
 end

data/lib/glyphs/rubocop.rb

@@ -18,7 +18,7 @@ module Glyphs
         LintRoller::About.new(
           name: "glyphs",
           version: Glyphs::VERSION,
-          homepage: "https://github.com/mhenrixon/glyphs",
+          homepage: "https://github.com/zoolutions/glyphs",
           description: "Icon-name validation and legacy icon-helper autocorrection for Glyphs components."
         )
       end

data/lib/glyphs/store.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Glyphs
+  # Per-Ractor lazy storage: `Store.fetch(:glyphs_svg_cache) { SvgCache.new }`.
+  #
+  # Adapted from conformance-kit's ConformanceKit::Store (MIT, same author),
+  # which glyphs cannot depend on at runtime. On CRuby (3.4+, the gem's floor)
+  # this is `Ractor.store_if_absent`: atomic, one value per Ractor. Engines
+  # without it (TruffleRuby, JRuby) get one Mutex-guarded Hash, created at load
+  # and only there, so on CRuby no unshareable module state exists at all.
+  module Store
+    class << self
+      def fetch(key, &)
+        return ::Ractor.store_if_absent(key, &) if native?
+
+        @fallback_lock.synchronize do
+          @fallback_values.fetch(key) { @fallback_values[key] = yield }
+        end
+      end
+
+      def native?
+        defined?(::Ractor) ? ::Ractor.respond_to?(:store_if_absent) : false
+      end
+    end
+
+    unless native?
+      @fallback_lock = Mutex.new
+      # Only on engines without Ractor: guarded by @fallback_lock, never read unlocked.
+      @fallback_values = {} # rubocop:disable ThreadSafety/MutableClassInstanceVariable
+    end
+  end
+end

data/lib/glyphs/svg_cache.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Glyphs
+  # A bounded LRU of SvgTemplates, one per Ractor (see Glyphs.svg_cache). The
+  # threads of a Ractor share it, so every access holds the instance's Mutex;
+  # the size limit is passed per write, so a reconfigured svg_cache_size
+  # applies to a cache that already exists.
+  class SvgCache
+    def initialize
+      @entries = {}
+      @lock = Mutex.new
+    end
+
+    # The cached value for `key` (never nil), marked most recently used; on a
+    # miss, the block's value, stored. Either way the cache is trimmed to
+    # `limit` entries, so a lowered svg_cache_size applies on the next call. The
+    # block runs under the lock, so a missing icon is rendered (and reported) once.
+    def compute_if_absent(key, limit)
+      @lock.synchronize do
+        hit = @entries[key]
+        insert(key, hit.nil? ? yield : hit, limit)
+      end
+    end
+
+    def store(key, value, limit)
+      @lock.synchronize { insert(key, value, limit) }
+    end
+
+    def size
+      @lock.synchronize { @entries.size }
+    end
+
+    def clear
+      @lock.synchronize { @entries.clear }
+      self
+    end
+
+    private
+
+    def insert(key, value, limit)
+      @entries.delete(key)
+      @entries[key] = value
+      @entries.shift while @entries.size > limit
+      value
+    end
+  end
+end

data/lib/glyphs/svg_template.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+module Glyphs
+  # A rendered <svg>, split once into its opening tag's attributes and the
+  # rest, so a cache hit applies a caller's attributes without the File.read
+  # and Nokogiri pass of a fresh render (Icons::Icon#svg).
+  #
+  # The attributes go through the icons gem's own Icons::Icon::Attributes
+  # (class token lists, nested data:/aria: hashes, `_` to `-`), collected into a
+  # Hash instead of a Nokogiri node, and are written the way libxml2 writes
+  # them: an attribute already on the tag is replaced in place, a new one is
+  # appended, `&`, `<` and `>` are escaped, and a value holding `"` but no `'`
+  # is single-quoted. What libxml2 writes specially (HTML boolean attributes,
+  # href/src/action, control characters) is not merged: #render returns nil and
+  # the caller renders it uncached. spec/glyphs/svg_template_spec.rb holds the
+  # output byte-for-byte to the icons gem's.
+  #
+  # A caller's data: replaces the library's default data (the icons gem merges
+  # them that way) and lands where the defaults would have, so data: calls use
+  # a template rendered with DATA_SLOT, whose marker attribute holds that place.
+  class SvgTemplate
+    DATA_SLOT = { data: { "glyphs-data-slot" => "" }.freeze }.freeze
+    SLOT_ATTRIBUTE = "data-glyphs-data-slot"
+
+    OPENING_TAG = /\A<svg((?:\s+[^\s=>]+(?:="[^"]*"|='[^']*')?)*)\s*>/
+    ATTRIBUTE = /\s+(([^\s=>]+)(?:="[^"]*"|='[^']*')?)/
+    ESCAPES = { "&" => "&amp;", "<" => "&lt;", ">" => "&gt;", '"' => "&quot;" }.freeze
+    ESCAPABLE = /[&<>"]/
+    # libxml2 writes HTML boolean attributes without their value and
+    # percent-encodes URI attributes.
+    SPECIAL_NAMES = %w[
+      checked compact declare defer disabled ismap multiple nohref noresize noshade nowrap readonly selected
+      href src action
+    ].to_h { |name| [name, true] }.freeze
+    UPPERCASE = /[A-Z]/
+    PLAIN_NAME = %r{\A[^\s"'<>/=\x00-\x1F\x7F]+\z}
+    CONTROL_CHARACTER = /[\x00-\x08\x0B\x0C\x0E-\x1F]/
+
+    attr_reader :svg
+
+    # `data_slot: true` for markup rendered with DATA_SLOT as its data:.
+    def initialize(svg, data_slot: false)
+      @svg = svg.frozen? ? svg : svg.dup.freeze
+      match = OPENING_TAG.match(@svg)
+      @rest = match&.post_match.freeze
+      @pairs = match && parse(match[1])
+      @slot = data_slot ? slot_index : nil
+      @pairs = nil if data_slot && @slot.nil? # no marker: nothing to merge onto
+      freeze
+    end
+
+    # The SVG with `attributes` applied, or nil when they cannot be merged
+    # exactly (the caller then renders them through the icons gem).
+    def render(attributes)
+      return @svg if attributes.empty?
+      return unless mergeable?(attributes)
+
+      pairs = merge(@pairs.dup, attributes)
+      build(pairs) if pairs
+    end
+
+    private
+
+    def parse(attributes)
+      attributes.scan(ATTRIBUTE).map { |fragment, name| [name.freeze, " #{fragment}".freeze].freeze }.freeze
+    end
+
+    def slot_index
+      @pairs&.index { |name, _| name == SLOT_ATTRIBUTE }
+    end
+
+    # A data: call needs the data: template, any other call the plain one.
+    def mergeable?(attributes)
+      !@pairs.nil? && attributes.key?(:data) == !@slot.nil?
+    end
+
+    def merge(pairs, attributes)
+      return if @slot && !splice_data(pairs, attributes.slice(:data))
+
+      merged = collect(@slot ? attributes.except(:data) : attributes)
+      return unless merged
+
+      merged.each { |name, fragment| assign(pairs, name, fragment) }
+      pairs
+    end
+
+    # Puts the data: attributes where the slot marker is, in order, replacing
+    # any already on the tag, then drops the marker. A caller's own attribute
+    # named like the marker would be dropped with it: that call renders uncached.
+    def splice_data(pairs, data)
+      merged = collect(data)
+      return false if merged.nil? || merged.any? { |name, _| name == SLOT_ATTRIBUTE }
+
+      slot = @slot
+      merged.each do |name, fragment|
+        index = pairs.index { |pair_name, _| pair_name == name }
+        next pairs[index] = [name, fragment] if index
+
+        pairs.insert(slot, [name, fragment])
+        slot += 1
+      end
+      pairs.delete_at(slot)
+    end
+
+    def assign(pairs, name, fragment)
+      index = pairs.index { |pair_name, _| pair_name == name }
+      if index
+        pairs[index] = [name, fragment]
+      else
+        pairs << [name, fragment]
+      end
+    end
+
+    # [[name, fragment], ...] in the order the icons gem would set them, or nil
+    # if any of them is one libxml2 writes specially.
+    def collect(attributes)
+      collected = {}
+      Icons::Icon::Attributes.new(arguments: attributes).attach(to: collected)
+      collected.map do |name, value|
+        name = name.to_s
+        value = value.to_s
+        return nil unless plain?(name, value)
+
+        [name, fragment(name, value)]
+      end
+    end
+
+    def plain?(name, value)
+      PLAIN_NAME.match?(name) && !special?(name) && value.valid_encoding? &&
+        (value.ascii_only? || value.encoding == Encoding::UTF_8) && !CONTROL_CHARACTER.match?(value)
+    end
+
+    def special?(name)
+      SPECIAL_NAMES.key?(name) || (UPPERCASE.match?(name) && SPECIAL_NAMES.key?(name.downcase))
+    end
+
+    def fragment(name, value)
+      return " #{name}=\"#{value}\"" unless ESCAPABLE.match?(value)
+
+      if value.include?('"') && !value.include?("'")
+        " #{name}='#{value.gsub(/[&<>]/, ESCAPES)}'"
+      else
+        " #{name}=\"#{value.gsub(ESCAPABLE, ESCAPES)}\""
+      end
+    end
+
+    def build(pairs)
+      svg = +"<svg"
+      pairs.each { |pair| svg << pair.last }
+      svg << ">" << @rest
+    end
+  end
+end

data/lib/glyphs/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Glyphs
-  VERSION = "0.2.3"
+  VERSION = "0.3.0"
 end

data/lib/glyphs.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "monitor"
 require "phlex"
 require "icons"
 require "zeitwerk"
@@ -32,21 +33,32 @@ Icons.config
 module Glyphs
   extend Phlex::Kit
 
-  @svg_cache = {}
-  @svg_cache_mutex = Mutex.new
+  # Guards the boot-time writers (configure, register_library, finalize!). A
+  # Monitor, so a configure block may call register_library. Main Ractor only:
+  # readers never take it, so svg_for runs in any Ractor once finalized.
+  @lock = Monitor.new
+  @configuration = Configuration.new
 
   class << self
+    # The current configuration: a plain read, shareable after finalize!.
+    attr_reader :configuration
+
     def configure
-      yield(configuration) if block_given?
+      @lock.synchronize { yield(@configuration) if block_given? }
       configuration
     end
 
-    def configuration
-      @configuration ||= Configuration.new
+    def reset_configuration!
+      @lock.synchronize { @configuration = Configuration.new }
     end
 
-    def reset_configuration!
-      @configuration = Configuration.new
+    # Freezes the configuration so svg_for can run inside a non-main Ractor
+    # (see Configuration#finalize!; never raises). Glyphs::Railtie calls it once
+    # a Rails app has booted; outside Rails, call it at the end of boot, after
+    # every configure. reset_configuration! (tests) starts over with a fresh one.
+    def finalize!
+      @lock.synchronize { @configuration.finalize! }
+      self
     end
 
     # Defines a `Glyphs::Icon` subclass for a custom icon library and exposes it
@@ -59,31 +71,51 @@ module Glyphs
       library = library.to_sym
       name = component.to_sym
 
-      if const_defined?(name, false)
-        existing = const_get(name, false)
-        return existing if existing < Icon && library == existing::LIBRARY
+      @lock.synchronize do
+        if const_defined?(name, false)
+          existing = const_get(name, false)
+          return existing if existing < Icon && library == existing::LIBRARY
 
-        raise ArgumentError, "Glyphs::#{name} is already defined and does not render the #{library} library"
-      end
+          raise ArgumentError, "Glyphs::#{name} is already defined and does not render the #{library} library"
+        end
 
-      klass = Class.new(Icon)
-      klass.const_set(:LIBRARY, library)
-      const_set(name, klass)
+        klass = Class.new(Icon)
+        klass.const_set(:LIBRARY, library)
+        const_set(name, klass)
+      end
     end
 
     # Returns the SVG markup for an icon, applying the configured missing-icon
-    # policy (raise / instrument / fallback) and an optional per-process cache.
+    # policy (raise / instrument / fallback) and the per-Ractor cache: one
+    # entry per [library, variant, name], the caller's attributes applied to
+    # the cached markup on every call.
     def svg_for(name:, library:, variant:, attributes:)
       return render_svg(name:, library:, variant:, attributes:) unless configuration.cache_svgs
 
-      key = [library, variant, name, attributes]
-      @svg_cache_mutex.synchronize do
-        @svg_cache[key] ||= render_svg(name:, library:, variant:, attributes:)
+      data = attributes.key?(:data)
+      template = svg_cache.compute_if_absent([library, variant, name, data], configuration.svg_cache_size) do
+        markup = render_svg(name:, library:, variant:, attributes: data ? SvgTemplate::DATA_SLOT : {})
+        SvgTemplate.new(markup, data_slot: data)
       end
+      template.render(attributes) || render_svg(name:, library:, variant:, attributes:)
+    end
+
+    # Seeds this Ractor's cache with markup rendered elsewhere, e.g. on the
+    # main Ractor (which can run the icons gem and Nokogiri) for a Ractor that
+    # cannot. Calls with a data: attribute still render through the icons gem.
+    def preload_svg(name:, library:, svg:, variant: nil)
+      key = [library.to_sym, variant&.to_sym, name.to_s.tr("_", "-"), false]
+      svg_cache.store(key, SvgTemplate.new(svg), configuration.svg_cache_size)
+    end
+
+    # The current Ractor's SvgCache.
+    def svg_cache
+      Store.fetch(:glyphs_svg_cache) { SvgCache.new }
     end
 
+    # Empties the current Ractor's cache (other Ractors keep theirs).
     def reset_cache!
-      @svg_cache_mutex.synchronize { @svg_cache = {} }
+      svg_cache.clear
     end
 
     private

data/lib/rubocop/cop/glyphs/icon_resolution.rb

@@ -11,6 +11,11 @@ module RuboCop
       # calls (`_lucide(:house)`) are validated. A literal `variant:` keyword is
       # honored; calls with dynamic names or variants are skipped.
       #
+      # A directory that does not exist is a configuration error, not "nothing
+      # to check": it warns once per library/variant, or — with `Strict` — adds
+      # an offence, so the cop can never quietly validate nothing. A directory
+      # that exists but ships no SVGs stays silent.
+      #
       # @example
       #   # bad
       #   LucideIcon(:non_existent_icon)
@@ -51,10 +56,14 @@ module RuboCop
 
         ICONIFY_PATTERN = /\biconify\s+(lucide|phosphor|heroicons)--([a-z0-9-]+)/
 
+        DEFAULT_ICONS_PATH = "app/assets/svg/icons"
+
         RAW_MSG = "Use `%{component}(:%{symbol}, class: \"%{rest}\")` instead of raw `iconify %{library}--…` class."
         RAW_DSTR_MSG = "Use `LucideIcon(name, class: ...)` etc. instead of building a raw " \
                        "`iconify <library>--…` class string."
         MISSING_MSG = "Icon `%{name}` not found in %{library}/%{variant}. %{suggestion}"
+        MISSING_DIR_MSG = "Icon directory `%{path}` not found, so `%{component}` names are not validated. " \
+                          "Sync the library or fix `IconsPath`/`Libraries`."
 
         def on_str(node)
           return if node.parent&.dstr_type?
@@ -97,7 +106,7 @@ module RuboCop
           @libraries ||= DEFAULT_LIBRARIES.merge(cop_config["Libraries"] || {})
         end
 
-        def check_call(node, _component, library)
+        def check_call(node, component, library)
           name = literal_name(node.first_argument)
           return unless name
 
@@ -105,6 +114,7 @@ module RuboCop
           return if variant == :dynamic
 
           available = available_icons(library["Dir"], variant)
+          return report_missing_directory(node, component, library["Dir"], variant) if available.nil?
           return if available.empty?
           return if available.include?(name)
 
@@ -124,6 +134,21 @@ module RuboCop
           end
         end
 
+        # The directory the cop was told to read is missing, so every call for
+        # this library goes unchecked. Report it rather than pass silently.
+        def report_missing_directory(node, component, library_dir, variant)
+          message = format(MISSING_DIR_MSG, path: configured_directory(library_dir, variant), component:)
+          return add_offense(node.first_argument, message:) if cop_config["Strict"]
+
+          self.class.warn_once("[Glyphs/IconResolution] #{message}")
+        end
+
+        # Built from the unexpanded `IconsPath` so the message shows the path as
+        # the project wrote it, not an absolute machine-specific one.
+        def configured_directory(library_dir, variant)
+          self.class.directory_for(cop_config["IconsPath"] || DEFAULT_ICONS_PATH, library_dir, variant)
+        end
+
         def variant_for(node, library)
           pair = variant_pair(node)
           return library["DefaultVariant"] if pair.nil?
@@ -258,24 +283,53 @@ module RuboCop
         end
 
         def icons_base_path
-          @icons_base_path ||= File.expand_path(cop_config["IconsPath"] || "app/assets/svg/icons", Dir.pwd)
+          @icons_base_path ||= File.expand_path(cop_config["IconsPath"] || DEFAULT_ICONS_PATH, Dir.pwd)
         end
 
         def available_icons(library_dir, variant)
           self.class.available_icons_for(icons_base_path, library_dir, variant)
         end
 
+        # Guards the two class-level memos below: RuboCop builds a cop instance
+        # per file, and a server or LSP process may inspect files on threads.
+        @memo_lock = Mutex.new
+
         class << self
+          # nil when the directory is absent, [] when it exists but ships no
+          # SVGs — the caller has to tell those apart. Memoized with `key?` (not
+          # `||=`) so a nil result is not re-probed on every call site.
           def available_icons_for(base_path, library_dir, variant)
-            @available_icons_cache ||= {}
-            @available_icons_cache[[base_path, library_dir, variant]] ||= load_icons(base_path, library_dir, variant)
+            key = [base_path, library_dir, variant]
+            @memo_lock.synchronize do
+              @available_icons_cache ||= {}
+              return @available_icons_cache[key] if @available_icons_cache.key?(key)
+
+              @available_icons_cache[key] = load_icons(directory_for(base_path, library_dir, variant))
+            end
+          end
+
+          def directory_for(base_path, library_dir, variant)
+            File.join(*[base_path, library_dir, variant].compact.reject { |part| part.to_s.empty? })
+          end
+
+          # RuboCop builds a fresh cop instance per file, so deduplicating the
+          # missing-directory warning has to outlive the instance.
+          def warn_once(message)
+            first = @memo_lock.synchronize do
+              @warned_messages ||= {}
+              !@warned_messages.key?(message) && (@warned_messages[message] = true)
+            end
+            warn message if first
+          end
+
+          def reset_warnings!
+            @memo_lock.synchronize { @warned_messages = nil }
           end
 
           private
 
-          def load_icons(base_path, library_dir, variant)
-            path = File.join(*[base_path, library_dir, variant].compact.reject { |part| part.to_s.empty? })
-            return [] unless Dir.exist?(path)
+          def load_icons(path)
+            return nil unless Dir.exist?(path)
 
             Dir.children(path).filter_map { |file| File.basename(file, ".svg") if file.end_with?(".svg") }.sort
           end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: glyphs
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 0.3.0
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -85,6 +85,9 @@ files:
 - lib/glyphs/rubocop.rb
 - lib/glyphs/sidekick_icon.rb
 - lib/glyphs/source_scanner.rb
+- lib/glyphs/store.rb
+- lib/glyphs/svg_cache.rb
+- lib/glyphs/svg_template.rb
 - lib/glyphs/tabler_icon.rb
 - lib/glyphs/version.rb
 - lib/glyphs/weather_icon.rb
@@ -93,13 +96,13 @@ files:
 - lib/rubocop/cop/glyphs/library_call_helpers.rb
 - lib/rubocop/cop/glyphs/prefer_library_component.rb
 - lib/tasks/glyphs.rake
-homepage: https://github.com/mhenrixon/glyphs
+homepage: https://github.com/zoolutions/glyphs
 licenses:
 - MIT
 metadata:
-  source_code_uri: https://github.com/mhenrixon/glyphs
-  changelog_uri: https://github.com/mhenrixon/glyphs/blob/main/CHANGELOG.md
-  bug_tracker_uri: https://github.com/mhenrixon/glyphs/issues
+  source_code_uri: https://github.com/zoolutions/glyphs
+  changelog_uri: https://github.com/zoolutions/glyphs/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/zoolutions/glyphs/issues
   default_lint_roller_plugin: Glyphs::RuboCop::Plugin
   rubygems_mfa_required: 'true'
 rdoc_options: []