boring_avatars 0.1.0

data/docs/rails-binding.md

@@ -0,0 +1,152 @@
+# Rails binding 設計
+
+## 目的
+
+Rails bindingは、Rails ViewからCoreのSVG生成を呼び出し、escape済みの結果を `ActiveSupport::SafeBuffer` として返す薄いadapterである。描画アルゴリズム、default値、validationをRails側に複製しない。
+
+Coreの契約は [Core ライブラリ設計](core-library.md)、全体構成は [アーキテクチャ](architecture.md)、ロード境界を含むテストは [テスト・互換性設計](testing-and-compatibility.md) を参照する。
+
+## opt-inロード
+
+次の2つのrequire pathは明確に異なる契約を持つ。
+
+```ruby
+require "boring_avatars"
+```
+
+- Coreだけをロードする。
+- ActiveSupport、ActionView、Rails bindingをロードしない。
+- Railsが既にロード済みでもhelperを登録しない。
+
+```ruby
+require "boring_avatars/bindings/rails"
+```
+
+- Coreをロードする。
+- `active_support/lazy_load_hooks` と `active_support/core_ext/string/output_safety` をロードする。
+- View Helperを定義し、ActionViewのlazy-load hookへ登録する。
+- ActionView自体をeager loadしない。
+
+Rails利用者はGemfileで自動require先を指定できる。
+
+```ruby
+gem "boring_avatars", require: "boring_avatars/bindings/rails"
+```
+
+または、GemfileではCoreだけを読み込み、initializerなどでbindingを明示的にrequireする。
+
+## Helper登録
+
+RailtieやEngineは作らず、entrypointで直接load hookを登録する。
+
+```ruby
+require "boring_avatars"
+require "active_support/lazy_load_hooks"
+require "active_support/core_ext/string/output_safety"
+require "boring_avatars/bindings/rails/view_helper"
+
+ActiveSupport.on_load(:action_view) do
+  include ::BoringAvatars::Bindings::Rails::ViewHelper
+end
+```
+
+`ActiveSupport.on_load` はActionViewが既にload hookを実行済みなら登録時に即時適用し、未ロードなら後の `run_load_hooks(:action_view, self)` で適用する。このため、次の両方を同じ契約として保証する。
+
+1. bindingをrequireした後にActionViewをロードする。
+2. ActionViewをロードした後にbindingをrequireする。
+
+gemのコードはRailsのapplication autoload pathやreload対象に置かない。`to_prepare`、initializer、Zeitwerk向け登録は不要とする。Rubyの `require` と同じく複数回のrequireは冪等でなければならない。
+
+## 依存関係
+
+`boring_avatars.gemspec` に `rails`、`railties`、`actionview`、`activesupport` のruntime dependencyを追加しない。RubyGemsにはoptional runtime dependencyの表現がないため、追加するとCoreだけの利用者にもRails系gemのinstallを強制してしまう。
+
+Rails bindingを利用するapplicationがRails／ActiveSupportを提供する。提供されていない環境でbindingをrequireした場合、`LoadError` をrescueせず伝播させる。警告だけでhelperを無効化する処理や、Coreへfallbackする処理は実装しない。
+
+開発・CIではRails系列ごとのGemfileからActionViewをdevelopment/test dependencyとして与える。
+
+## View Helper API
+
+公開helperは `boring_avatar` だけとする。
+
+```ruby
+boring_avatar(
+  name,
+  variant: :marble,
+  colors: ["#92A1C6", "#146A7C", "#F0AB3D", "#C271B4", "#C20D90"],
+  size: "40px",
+  square: false,
+  title: false,
+  id_prefix: nil,
+  **svg_attributes
+) # => ActiveSupport::SafeBuffer
+```
+
+- semantic optionの意味とvalidationはCoreと同じである。
+- Rails独自defaultは持たない。
+- Coreの `attributes:` 引数はhelperでは公開せず、残りのkeywordをroot SVG属性として扱う。
+- 未知keywordは属性allowlistで検証され、許可されていなければ `ArgumentError` になる。
+- Coreが送出した例外はそのまま呼び出し元へ伝える。
+
+### 使用例
+
+```erb
+<%= boring_avatar(
+  current_user.email,
+  variant: :bauhaus,
+  size: "3rem",
+  class: ["avatar", "avatar--navigation"],
+  aria: { label: "#{current_user.name}のavatar" },
+  data: { controller: "avatar", user_id: current_user.id }
+) %>
+```
+
+`name`、palette、属性値にuser inputが含まれていても、値はCore serializerでescapeされる。呼び出し側で `raw` や `html_safe` を付ける必要はない。
+
+## Rails形式属性の正規化
+
+helperはCoreのflat属性allowlistに合わせ、次のRails向けshorthandだけを正規化する。
+
+- `class:` はString、またはStringだけを含むArrayを許可する。Arrayは空要素を除外せず、空文字があれば `ArgumentError` とし、半角spaceで結合する。
+- `data:` はHashを受け、keyの `_` を `-` に変換して `data-<key>` へ展開する。
+- `aria:` はHashを受け、keyの `_` を `-` に変換して `aria-<key>` へ展開する。
+- `id`、`lang`、`tabindex`、`focusable` はCoreと同じscalar値を受ける。
+- `nil` は属性を省略し、booleanは文字列 `true` / `false` として渡す。
+
+`data:` / `aria:` のnested Hash、ArrayやHashの自動JSON化、`class` 以外のArray展開は初版では扱わない。正規化後に同じ属性名が複数回現れた場合は、後勝ちにせず `ArgumentError` とする。
+
+属性値が `ActiveSupport::SafeBuffer` であってもsafeという印を信頼せず、Coreでは通常のStringとして再度XML escapeする。
+
+## 内部IDの一意性
+
+Reactの `useId` に相当する一意性をRails View内で得るため、helperは `id_prefix: nil` の各呼び出しで次のprefixを生成する。
+
+```ruby
+"ba-#{SecureRandom.hex(10)}"
+```
+
+生成したprefixをCoreの `id_prefix:` へ渡し、完成後のSVGを文字列置換しない。20桁hexの衝突確率は実用上無視でき、partial、fragment cache、Turboで別render結果が同じdocumentへ追加される場合にもview-local counterより安全である。
+
+呼び出し側が有効な `id_prefix` を明示した場合はそれをそのままCoreへ渡す。snapshotや固定HTMLを必要とする場合は、テストやapplication側で明示prefixを使える。
+
+## HTML safety
+
+`html_safe` はescape処理ではなく、「これ以上escapeしなくてよい」という信頼宣言である。次の順序を変更しない。
+
+1. helperがRails形式属性を通常のRuby値へ正規化する。
+2. Coreが全入力を検証し、element treeを作る。
+3. Core serializerがtitle textとすべての属性値をXML escapeする。
+4. Coreが完成済みの通常のStringを返す。
+5. helperが最後に一度だけSafeBuffer化する。
+
+SafeBuffer化後にname、属性、ID、wrapper markupを連結してはならない。生成済み `<svg>` 開始tagを正規表現で差し替える方法や、Railsの `tag.attributes` が返すmarkupをraw挿入する方法も採用しない。
+
+## Loadと安全性の受け入れ条件
+
+- Core require後の `$LOADED_FEATURES` にActiveSupport、ActionView、Rails bindingがない。
+- Railsが先にロードされてもCore requireだけでは `boring_avatar` が追加されない。
+- bindingとActionViewのどちらを先にロードしても最終的にhelperが利用できる。
+- helperの戻り値が `ActiveSupport::SafeBuffer` かつ `html_safe?` である。
+- Core出力とhelper出力は、helperが付与する内部ID以外のDOM構造が一致する。
+- 同じViewで2回呼んだ結果の内部ID集合が交差せず、すべてのfragment参照が各SVG内で解決する。
+- Railsが存在しない場合にbinding requireが黙って成功しない。

data/docs/testing-and-compatibility.md

@@ -0,0 +1,201 @@
+# テスト・互換性設計
+
+## 互換性の基準
+
+移植基準は `boringdesigners/boring-avatars` のfull SHA [`d0ff2582a8921b643a89de4a4912be28938a828b`](https://github.com/boringdesigners/boring-avatars/tree/d0ff2582a8921b643a89de4a4912be28938a828b) とする。このcommitの `package.json` は2.0.4だが、GitHub latest releaseはv2.0.2である。fixture、設計書、third-party noticeにはshort SHAや可変の `master` URLではなくfull SHAを記録する。
+
+テスト対象のCore APIは [Core ライブラリ設計](core-library.md)、Rails固有のload/safety契約は [Rails binding 設計](rails-binding.md)、実装順は [アーキテクチャ](architecture.md) を参照する。
+
+## 「描画互換」の定義
+
+有効な入力について、次を移植元と一致させる。
+
+- UTF-16 code unitとsigned 32-bit overflowによるname hash
+- paletteから色を選ぶindexと順序
+- variantごとの固定path、要素数、要素順
+- 座標、サイズ、角丸、回転、移動、scale
+- Beamの顔色contrast、目、口、wrapper形状
+- Marbleのblur filterとoverlay blend
+- Pixelのrect配置と描画順
+- Sunsetのgradient方向
+- Ringのlayer構成
+- 共通maskによるround/square形状
+
+比較対象外は次のとおり。
+
+- React component APIとReact propsの型
+- React `useId` が生成する文字列
+- attribute順、self-closing表記などReactとRuby serializerの字句差
+- whitespaceだけの差
+- byte-for-byteのSVG文字列
+
+互換性テストは視覚的な印象だけで判断せず、正規化したSVG DOMの構造と属性値で判定する。
+
+## 意図的な非互換
+
+| 移植元 | Ruby版 |
+|---|---|
+| name省略時は `Clara Barton` | nameは必須。空文字は許可 |
+| 未知variantは `marble` | `ArgumentError` |
+| `geometric` / `abstract` alias | 非対応、`ArgumentError` |
+| 空paletteや無効色の挙動は未定義 | 1色以上の `#RRGGBB` を必須化 |
+| 任意のReact SVG propsで固定属性も上書き可能 | 安全なroot属性allowlistだけ許可 |
+| mask/filter IDはReact tree依存 | Coreは入力digest、Railsはrandom prefix |
+| Sunset gradient IDは空白除去name | 安全なprefix由来ID |
+| Reactがmarkupをescape | CoreのXML serializerが一元的にescape |
+
+これらを後方互換目的でalias、fallback、警告付き受理へ変更しない。移植元の更新を取り込む場合も、Ruby版の公開契約変更として個別に判断する。
+
+## テスト基盤
+
+- test frameworkはMinitestとする。
+- `rake test` をローカルとCIの共通entrypointにする。
+- `rake typecheck` で配布対象のRBSとSorbet RBIを検証する。RBSは `rbs -I sig validate` とSteepの公開API契約fixture、SorbetはRBIと `# typed: strong` の公開API契約fixtureを入力にする。実装本体へのSorbet導入とは分離する。
+- 公開API manifestは実装から取得したpublic method集合と完全一致させ、Sorbet/RBS双方の契約fixtureが全項目を使用することを検査する。Sorbet fixtureの `untyped_usages` はゼロを必須とし、公開API型カバレッジ100%をCIの失敗条件にする。
+- SVG parsingとcanonical比較にはdevelopment/test dependencyとしてNokogiriを使用し、runtime dependencyには追加しない。
+- processごとのload状態を検証するテストは `Open3.capture3` などで新しいRuby processを起動する。
+- Rails系列は `BUNDLE_GEMFILE` で切り替える明示的なmatrix Gemfileを使用し、Appraisalによる生成物を必須にしない。
+
+テストは内部private methodへ過度に依存せず、公開出力、pinned fixture、load stateを中心にする。ただしJavaScript互換hashはアルゴリズムの破壊を早く特定できるよう、独立したunit testも持つ。
+
+## Upstream fixture
+
+移植元にはunit testや公式snapshotがないため、pinned commitからReact server-side renderingでfixtureを生成する。
+
+### 生成手順
+
+1. pinned SHAを一時directoryへcheckoutする。
+2. lockfileどおり `npm ci` とbuildを行う。
+3. `react-dom/server` の `renderToStaticMarkup` で公開 `Avatar` componentを描画する。
+4. 入力optionとraw SVGをfixtureへ保存する。
+5. fixture metadataへupstream repository、full SHA、Node/npm version、生成commandを記録する。
+
+fixture更新scriptはnetworkやupstreamのdefault branchを暗黙参照せず、記録されたSHAを必須引数にする。通常のRuby test実行時はNodeやnetworkを必要とせず、commit済みfixtureだけを読む。
+
+実装済みの更新commandは `script/update_upstream_fixtures PATH_TO_PINNED_CHECKOUT` とする。指定checkoutのHEADが上記full SHAと一致しない場合は、fixtureを書き換える前に失敗する。
+
+### DOM正規化
+
+ReactとRubyで異なる内部IDを比較可能にするため、双方をXMLとしてparseし、次の正規化を行う。
+
+1. document順に各 `id` を `internal-1`、`internal-2` のようなtokenへmapする。
+2. `mask`、`filter`、`fill` などの `url(#id)` fragment参照も同じmapで置換する。
+3. attribute順とempty-element表記をXML canonicalizationで統一する。
+4. style宣言はproperty/valueを保ったまま、serializer由来の空白だけを正規化する。
+5. ID以外の値、要素順、path data、transform、色は変更しない。
+
+参照先のないfragment、重複して異なる定義を持つID、SVG外を参照するURLがあれば、正規化前にテストを失敗させる。
+
+## Fixtureケース
+
+最低限、次を固定fixtureまたはtable-driven testとして持つ。
+
+### 描画
+
+- 全6 variant × default palette × `Maria Mitchell`
+- 全6 variantの `square: true`
+- 全6 variantの `title: true`
+- palette長1、2、5
+- 数値sizeとstring size
+- ASCIIの似た名前と長い名前
+
+### Unicode/hash
+
+- 空文字
+- `Clara Barton`
+- `日本語`
+- `😀`
+- 合成文字 `é`
+- 分解文字 `e\u0301`
+
+期待hashはCore設計に記載したvectorと一致させる。emojiはUTF-16 surrogate pairとして処理されることを個別に確認する。
+
+### Validationとsecurity
+
+- `nil` やString以外のname
+- invalid encodingとXML 1.0で禁止されるcontrol character
+- 空palette、String以外のpalette、無効hex、空要素
+- 未知variant、case違い、`geometric`、`abstract`
+- `nil`、0、負数、NaN、Infinity、不正grammarのsize
+- boolean以外のsquare/title
+- 不正または長すぎるID prefix
+- allowlist外属性、正規化後の重複属性、非scalar値
+- tagやquoteを含むname、class、data、aria値
+- `style`、`href`、`xlink:href`、`onload`、固定構造属性の拒否
+
+悪意ある値のテストは単に文字列に `<script>` がないことを見るだけでなく、XML parse後に想定外の要素・属性が増えていないことを確認する。
+
+## 内部IDテスト
+
+Coreについて次を確認する。
+
+- 同じ全入力から同じprefixとSVGが生成される。
+- name、variant、palette、squareのいずれかが変わればprefixが変わる。
+- size、title、追加root属性だけを変えてもdefs用prefixは変わらない。
+- 全 `url(#...)` が同じSVG内の一意なIDへ解決する。
+- Sunsetで同じname・異なるpaletteを並べてもgradientが混線しない。
+
+Rails helperについて次を確認する。
+
+- `SecureRandom` をstubしたテストでは指定prefixの安定したSVGを得られる。
+- 通常の2回の呼び出しでは内部ID集合が互いに素になる。
+- 明示的な `id_prefix` はCoreと同じvalidationを受ける。
+
+## Require境界テスト
+
+各シナリオを新しいRuby processで実行する。
+
+1. `require "boring_avatars"` のみでActiveSupport/ActionViewがロードされず、helperが存在しない。
+2. ActionViewを先にロードしてからCoreだけをrequireしてもhelperが追加されない。
+3. bindingをrequireしてからActionViewをロードするとhelperが追加される。
+4. ActionViewをロードしてからbindingをrequireしてもhelperが追加される。
+5. bindingを複数回requireしてもmodule ancestorや動作が重複しない。
+6. Rails系gemを利用できない環境でbinding requireが `LoadError` になる。
+7. helperの戻り値が `ActiveSupport::SafeBuffer` かつ `html_safe? == true` になる。
+8. Core validation errorがhelperから変更されず伝播する。
+
+`$LOADED_FEATURES`、ActionViewのancestors、helper呼び出し結果を組み合わせ、定数が偶然定義されているだけの状態を成功とみなさない。
+
+## 対応matrix
+
+初版の `required_ruby_version` は `>= 3.3` とする。Core CIは次のRuby系列の最新patchを対象にする。
+
+- Ruby 3.3
+- Ruby 3.4
+- Ruby 4.0
+
+Rails bindingはActionView 8.0と8.1の最新patchをmatrix Gemfileで固定し、上記Ruby系列との全組み合わせをCI対象にする。dependency resolution不能な組み合わせを黙ってallow-failureにせず、対応範囲または依存選択の誤りとして解決する。
+
+Rails 7以前と未検証の将来Rails majorはサポート対象に含めない。RailsがoptionalであるためgemspecにはRails version constraintを置かず、文書とCI結果を保証範囲の根拠とする。
+
+## Gem package検証
+
+built gemに対して次を検証する。
+
+- CoreとRails bindingの必要ファイルが含まれる。
+- test、fixture、一時生成物、upstream checkoutを不要に同梱しない。
+- Rails、ActionView、ActiveSupportのruntime dependencyがない。
+- `required_ruby_version >= 3.3` が設定されている。
+- gem metadataのlicenseがMITである。
+- projectのLICENSEとupstream noticeが含まれる。
+
+## ライセンス
+
+移植元はMIT Licenseで、`Copyright (c) 2021 boringdesigners` の表示を持つ。Ruby版もMITとし、将来の実装・配布時には次を満たす。
+
+- project自身の `LICENSE` を置く。
+- upstreamのcopyrightとMIT license本文を `THIRD_PARTY_NOTICES.md` などへ実体として収録する。
+- gemspecの `license` / `licenses` とpackage対象へ反映する。
+- built gemにLICENSEとnoticeが含まれることを自動テストする。
+
+単にupstream URLだけを記載してlicense本文を省略してはならない。
+
+## 完成条件
+
+- pinned fixtureとの正規化DOM比較が全6 variantで成功する。
+- hash vector、validation、security、ID参照の全テストが成功する。
+- Core-only requireとRails opt-in requireの境界が別processテストで保証される。
+- Ruby 3.3・3.4・4.0およびRails 8.0・8.1 matrixが成功する。
+- built gemの依存・同梱物・license検査が成功する。
+- built gemに `sig/boring_avatars.rbs` と `rbi/boring_avatars.rbi` が同梱され、両方の型検証が成功する。
+- 4つの設計文書でAPI、default、対応範囲、意図的非互換が一致している。

data/lib/boring_avatars/bindings/rails/view_helper.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module BoringAvatars
+  module Bindings
+    module Rails
+      module ViewHelper
+        UNSPECIFIED = Object.new.freeze
+
+        def boring_avatar(
+          name,
+          variant: :marble,
+          colors: UNSPECIFIED,
+          size: "40px",
+          square: false,
+          title: false,
+          id_prefix: nil,
+          **svg_attributes
+        )
+          prefix = id_prefix || "ba-#{SecureRandom.hex(10)}"
+          options = {
+            variant: variant,
+            size: size,
+            square: square,
+            title: title,
+            id_prefix: prefix,
+            attributes: normalize_boring_avatar_attributes(svg_attributes)
+          }
+          options[:colors] = colors unless colors.equal?(UNSPECIFIED)
+
+          svg = BoringAvatars.generate(name, **options)
+          svg.html_safe
+        end
+
+        private
+
+        def normalize_boring_avatar_attributes(attributes)
+          normalized = {}
+          attributes.each do |name, value|
+            next if value.nil?
+
+            case name.to_s
+            when "class"
+              store_boring_avatar_attribute(normalized, "class", normalize_boring_avatar_class(value))
+            when "data", "aria"
+              expand_boring_avatar_attributes(normalized, name.to_s, value)
+            else
+              normalized_name = normalize_boring_avatar_attribute_name(name)
+              store_boring_avatar_attribute(normalized, normalized_name, value)
+            end
+          end
+          normalized
+        end
+
+        def normalize_boring_avatar_class(value)
+          return value if value.is_a?(String)
+
+          unless value.is_a?(Array) && value.all? { |item| item.is_a?(String) && !item.empty? }
+            raise ArgumentError, "class must be a String or an Array of non-empty Strings"
+          end
+
+          value.join(" ")
+        end
+
+        def expand_boring_avatar_attributes(normalized, prefix, value)
+          raise ArgumentError, "#{prefix} must be a Hash" unless value.is_a?(Hash)
+
+          value.each do |nested_name, nested_value|
+            suffix = normalize_boring_avatar_nested_attribute_name(nested_name)
+            store_boring_avatar_attribute(normalized, "#{prefix}-#{suffix}", nested_value)
+          end
+        end
+
+        def normalize_boring_avatar_nested_attribute_name(value)
+          case value
+          when String, Symbol
+            value.to_s.tr("_", "-")
+          else
+            raise ArgumentError, "nested SVG attribute names must be String or Symbol"
+          end
+        end
+
+        def normalize_boring_avatar_attribute_name(value)
+          case value
+          when String
+            value
+          when Symbol
+            value.to_s.tr("_", "-")
+          else
+            raise ArgumentError, "SVG attribute names must be String or Symbol"
+          end
+        end
+
+        def store_boring_avatar_attribute(attributes, name, value)
+          raise ArgumentError, "duplicate SVG attribute: #{name}" if attributes.key?(name)
+
+          attributes[name] = value
+        end
+
+        private_constant :UNSPECIFIED
+      end
+    end
+  end
+end

data/lib/boring_avatars/bindings/rails.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "boring_avatars"
+require "active_support/lazy_load_hooks"
+require "active_support/core_ext/string/output_safety"
+require "boring_avatars/bindings/rails/view_helper"
+
+ActiveSupport.on_load(:action_view) do
+  include ::BoringAvatars::Bindings::Rails::ViewHelper
+end
+

data/lib/boring_avatars/identifier.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module BoringAvatars
+  module Identifier
+    module_function
+
+    def call(input)
+      return input.id_prefix if input.id_prefix
+
+      parts = [
+        "v1",
+        input.variant.to_s,
+        input.square ? "1" : "0",
+        input.name,
+        input.colors.length.to_s,
+        *input.colors
+      ]
+      canonical = parts.map { |part| "#{part.bytesize}:#{part}" }.join
+      "ba-#{Digest::SHA256.hexdigest(canonical)[0, 20]}"
+    end
+  end
+end
+

data/lib/boring_avatars/input.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require_relative "svg/serializer"
+
+module BoringAvatars
+  DEFAULT_COLORS = ["#92A1C6", "#146A7C", "#F0AB3D", "#C271B4", "#C20D90"].map(&:freeze).freeze
+  VARIANTS = %w[marble beam pixel sunset ring bauhaus].freeze
+  COLOR_PATTERN = /\A#[0-9A-Fa-f]{6}\z/
+  SIZE_PATTERN = /\A(?<number>(?:\d+(?:\.\d+)?)|(?:\.\d+))(?<unit>px|em|rem|%|vw|vh|vmin|vmax)?\z/
+  ID_PREFIX_PATTERN = /\A[A-Za-z][A-Za-z0-9_-]{0,63}\z/
+  ATTRIBUTE_PATTERN = /\A(?:id|class|lang|tabindex|focusable|(?:aria|data)-[a-z0-9]+(?:-[a-z0-9]+)*)\z/
+
+  Input = Data.define(:name, :variant, :colors, :size, :square, :title, :id_prefix, :attributes) do
+    def initialize(
+      name:,
+      variant: :marble,
+      colors: DEFAULT_COLORS,
+      size: "40px",
+      square: false,
+      title: false,
+      id_prefix: nil,
+      attributes: {}
+    )
+      super(
+        name: normalize_string(name, "name"),
+        variant: normalize_variant(variant),
+        colors: normalize_colors(colors),
+        size: normalize_size(size),
+        square: normalize_boolean(square, "square"),
+        title: normalize_boolean(title, "title"),
+        id_prefix: normalize_id_prefix(id_prefix),
+        attributes: normalize_attributes(attributes)
+      )
+    end
+
+    private
+
+    def normalize_string(value, label)
+      raise ArgumentError, "#{label} must be a String" unless value.is_a?(String)
+
+      normalized = value.encode(Encoding::UTF_8)
+      unless Svg::Serializer.valid_xml_string?(normalized)
+        raise ArgumentError, "#{label} contains characters forbidden by XML 1.0"
+      end
+
+      normalized.freeze
+    rescue EncodingError => error
+      raise ArgumentError, "#{label} must be convertible to UTF-8: #{error.message}"
+    end
+
+    def normalize_variant(value)
+      variant = case value
+                when String then normalize_string(value, "variant")
+                when Symbol then normalize_string(value.to_s, "variant")
+                else raise ArgumentError, "variant must be a String or Symbol"
+                end
+      raise ArgumentError, "unknown variant: #{variant.inspect}" unless VARIANTS.include?(variant)
+
+      variant.to_sym
+    end
+
+    def normalize_colors(value)
+      raise ArgumentError, "colors must be a non-empty Array" unless value.is_a?(Array) && !value.empty?
+
+      value.map.with_index do |color, index|
+        normalized = normalize_string(color, "colors[#{index}]")
+        raise ArgumentError, "colors[#{index}] must use #RRGGBB format" unless COLOR_PATTERN.match?(normalized)
+
+        normalized
+      end.freeze
+    end
+
+    def normalize_size(value)
+      case value
+      when Integer
+        raise ArgumentError, "size must be greater than zero" unless value.positive?
+        value
+      when Float
+        raise ArgumentError, "size must be finite and greater than zero" unless value.finite? && value.positive?
+        value
+      when String
+        normalized = normalize_string(value, "size")
+        match = SIZE_PATTERN.match(normalized)
+        unless match && match[:number].to_f.positive?
+          raise ArgumentError, "size has an unsupported format"
+        end
+        normalized
+      else
+        raise ArgumentError, "size must be an Integer, Float, or String"
+      end
+    end
+
+    def normalize_boolean(value, label)
+      return value if value.equal?(true) || value.equal?(false)
+
+      raise ArgumentError, "#{label} must be true or false"
+    end
+
+    def normalize_id_prefix(value)
+      return if value.nil?
+
+      normalized = normalize_string(value, "id_prefix")
+      raise ArgumentError, "id_prefix has an unsupported format" unless ID_PREFIX_PATTERN.match?(normalized)
+
+      normalized
+    end
+
+    def normalize_attributes(value)
+      raise ArgumentError, "attributes must be a Hash" unless value.is_a?(Hash)
+
+      normalized = {}
+      seen = {}
+      value.each do |name, attribute_value|
+        normalized_name = normalize_attribute_name(name)
+        raise ArgumentError, "duplicate SVG attribute: #{normalized_name}" if seen.key?(normalized_name)
+
+        seen[normalized_name] = true
+
+        next if attribute_value.nil?
+
+        normalized[normalized_name.freeze] = normalize_attribute_value(attribute_value, normalized_name)
+      end
+      normalized.sort.to_h.freeze
+    end
+
+    def normalize_attribute_name(value)
+      name = case value
+             when String then normalize_string(value, "SVG attribute name")
+             when Symbol then normalize_string(value.to_s.tr("_", "-"), "SVG attribute name")
+             else raise ArgumentError, "SVG attribute names must be String or Symbol"
+             end
+      raise ArgumentError, "unsupported SVG attribute: #{name}" unless ATTRIBUTE_PATTERN.match?(name)
+
+      name
+    end
+
+    def normalize_attribute_value(value, name)
+      case value
+      when String
+        normalize_string(value, "attribute #{name}")
+      when Numeric
+        if value.respond_to?(:finite?) && !value.finite?
+          raise ArgumentError, "attribute #{name} must be finite"
+        end
+        value
+      when true, false
+        value
+      else
+        raise ArgumentError, "attribute #{name} has an unsupported value type"
+      end
+    end
+  end
+  private_constant :Input, :DEFAULT_COLORS, :VARIANTS, :COLOR_PATTERN, :SIZE_PATTERN,
+                   :ID_PREFIX_PATTERN, :ATTRIBUTE_PATTERN
+end

data/lib/boring_avatars/name_hash.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module BoringAvatars
+  module NameHash
+    UINT32_MASK = 0xFFFF_FFFF
+    INT32_SIGN = 0x8000_0000
+    UINT32_SIZE = 0x1_0000_0000
+
+    module_function
+
+    def call(name)
+      name.encode(Encoding::UTF_16LE).unpack("v*").reduce(0) do |hash, code_unit|
+        value = ((hash * 31) + code_unit) & UINT32_MASK
+        value >= INT32_SIGN ? value - UINT32_SIZE : value
+      end.abs
+    end
+  end
+end
+