vehicles 0.4.1 → 0.8.0

data/lib/vehicles/configuration.rb

@@ -22,13 +22,28 @@ module Vehicles
     # works on the bundled data — the gem is standalone first, SDK second.
     attr_accessor :api_key
 
-    # Base URL for the hosted VehiclesDB API. Overridable for self-hosting/testing.
+    # Where the hosted VehiclesDB API lives — the ORIGIN, without the /api/v1
+    # (endpoint paths carry it: HostedProvider::API_PREFIX). Overridable for
+    # self-hosting, staging or a local server: "http://localhost:3030".
     attr_accessor :api_base_url
 
     # Network timeout (seconds) for hosted API calls. Kept short so a slow/missing
     # API never blocks a request — hosted lookups degrade to the local data.
     attr_accessor :api_timeout
 
+    # Plate templates (Vehicles::Plates.template / .render): where fetched
+    # templates are kept, and for how long. Any store with read(key) and
+    # write(key, value, expires_in:) works — `Rails.cache` shares them across
+    # processes. Defaults to an in-process cache. Templates are public and
+    # carry nothing personal, so a long TTL is safe; the server re-renders
+    # them only when VehiclesDB's plate art changes.
+    attr_writer :plate_template_cache
+    attr_accessor :plate_template_ttl
+
+    def plate_template_cache
+      @plate_template_cache ||= Plates::TemplateCache.new
+    end
+
     # Extra make aliases, merged over the built-in ones. Keys are matched
     # forgivingly (case/diacritics-insensitive); values are canonical make names.
     attr_reader :aliases
@@ -63,7 +78,7 @@ module Vehicles
     def initialize
       @region          = nil # no continent filter by default (global dataset)
       @api_key         = nil
-      @api_base_url    = "https://api.vehiclesdb.com"
+      @api_base_url    = "https://vehiclesdb.com"
       @api_timeout     = 2
       @aliases         = {}
       @other_label     = "Other"
@@ -71,6 +86,7 @@ module Vehicles
       @cache_path      = default_cache_path
       @use_cache       = true
       @refresh_timeout = 5
+      @plate_template_ttl = 86_400 # a day, the server's own shared-cache lifetime
     end
 
     # Normalize alias keys at assignment time so lookups stay O(1) and forgiving.

data/lib/vehicles/dataset.rb

@@ -78,7 +78,11 @@ module Vehicles
     end
 
     # Resolve a make from a String/Symbol/Make via aliases, slug, or name.
-    def find_make(query)
+    # With `fuzzy:` (the default), a query that matches nothing exactly falls
+    # back to the closest make by edit distance — "marcedes" → Mercedes-Benz —
+    # but only when ONE make is strictly closest; equally close makes → nil.
+    # Pass `fuzzy: false` where a typo must NOT count as a match (validators).
+    def find_make(query, fuzzy: true)
       return query if query.is_a?(Make)
 
       q = Vehicles.normalize(query)
@@ -95,25 +99,31 @@ module Vehicles
       end
 
       # 3. direct slug / normalized name / make alias
-      @by_slug[q] || @index[q]
+      # 4. bounded edit-distance fallback over names/slugs/aliases (Fuzzy);
+      #    user-configured aliases are not fuzzy-matched
+      #    — never for the "Other" escape hatch's label ("Otra" is one edit
+      #    from the make Ora; Vehicles.models("Otra", include_other: true)
+      #    must stay [other_label])
+      #    — and never for id/slug/path-shaped input (Fuzzy.eligible_input?)
+      fuzzy &&= Fuzzy.eligible_input?(query) && !Vehicles.other?(query)
+      @by_slug[q] || @index[q] || (fuzzy ? Fuzzy.unique_closest(q, fuzzy_keys) : nil)
     end
 
     # Resolve a free-text "make + model" string into one Model. Tries the longest
     # leading make prefix first ("land rover defender"), then the remainder as the
     # model. Returns nil if nothing matches.
-    def find_model(query)
+    #
+    # The exact pass runs first over EVERY split; only if nothing matches is
+    # the make prefix retried with typo tolerance, so no answer that resolved
+    # before 0.7.8 can change ("volkswagon golf" now resolves; "vw golf" is
+    # answered by the exact pass exactly as before).
+    def find_model(query, fuzzy: true)
       q = Vehicles.normalize(query)
       tokens = q.split
       return nil if tokens.empty?
 
-      (tokens.length - 1).downto(1) do |i|
-        make = find_make(tokens[0, i].join(" "))
-        next unless make
-
-        model = make.model(tokens[i..].join(" "))
-        return model if model
-      end
-      nil
+      fuzzy &&= Fuzzy.eligible_input?(query) # ids/slugs/paths resolve exactly or not at all
+      model_by_split(tokens, fuzzy: false) || (fuzzy ? model_by_split(tokens, fuzzy: true) : nil)
     end
 
     # Every model whose name (or full name) matches the query, ranked: exact name,
@@ -148,20 +158,43 @@ module Vehicles
       @kinds ||= @makes.flat_map(&:kinds).uniq.sort.freeze
     end
 
-    # Ranked models by popularity: global decile first, then breadth of
-    # availability as the tiebreaker, then name. Unranked models (nil decile —
-    # catalog-only evidence) never appear: "unknown" must not outrank "known".
-    #   top_models(kind: :car, country: :nl, limit: 10)
+    # Ranked models by popularity. Unranked models (nil decile — catalog-only
+    # evidence) never appear: "unknown" must not outrank "known".
+    #
+    # Without `country:` — global decile, then breadth of availability, then
+    # name. WITH `country:` — that country's OWN rank (Model#rank_in) first,
+    # so a UK list reads in UK order, not in the presence-weighted global
+    # order (until 0.7.7 a filtered list kept the global sort). Models
+    # available there but without a rank there follow, in global order; a
+    # snapshot without `country_ranks` (data before 2026.10) degrades to the
+    # 0.7.7 order. Ranks are per KIND, so pass `kind:` for a clean ranking —
+    # without it, kinds interleave by rank (car #1, motorcycle #1, …).
+    #
+    # `by:` picks the decile: :global_decile (default — presence average,
+    # "popular in many places") or :mass_decile (per-kind registration mass,
+    # "how many exist"; data 2026.10.1+). Records without the chosen decile
+    # never appear, so `by: :mass_decile` on an older snapshot returns [].
+    #   top_models(kind: :car, country: :gb, limit: 10)
+    # With `country:`, the country's own rank still sorts first and the
+    # chosen decile only breaks ties among models ranked equally there.
+    #   top_models(kind: :car, by: :mass_decile, limit: 10)
     #   top_models(kind: :motorcycle, region: :as, limit: 10)  # by continent
-    def top_models(kind: nil, country: nil, region: nil, limit: 20)
+    def top_models(kind: nil, country: nil, region: nil, limit: 20, by: :global_decile)
+      raise ArgumentError, "by: must be :global_decile or :mass_decile" unless RANKINGS.include?(by)
+
       c = country&.to_s&.downcase
-      list = all_models.select(&:global_decile)
+      list = all_models.select(&by)
       list = list.select { |m| m.kind == kind.to_sym } if kind
       list = list.select { |m| m.availability.include?(c) } if c
       list = list.select { |m| m.available_in_region?(region) } if region
-      list.sort_by { |m| [m.global_decile, -m.availability.size, m.name] }.first(limit)
+      list.sort_by do |m|
+        rank = c && m.rank_in(c)
+        [rank ? 0 : 1, rank || 0, m.public_send(by), -m.availability.size, m.name]
+      end.first(limit)
     end
 
+    RANKINGS = %i[global_decile mass_decile].freeze
+
     # Every model matching optional kind/region/rarity filters, ranked by
     # popularity. The "give me a sensible slice" entry point.
     def all_models_filtered(kind: nil, region: nil, rarity: nil, max_decile: nil)
@@ -186,6 +219,28 @@ module Vehicles
       @index[Vehicles.normalize(key)] ||= make
     end
 
+    # The longest-make-prefix split behind #find_model, one pass.
+    def model_by_split(tokens, fuzzy:)
+      (tokens.length - 1).downto(1) do |i|
+        make = find_make(tokens[0, i].join(" "), fuzzy: fuzzy)
+        next unless make
+
+        model = make.model(tokens[i..].join(" "))
+        return model if model
+      end
+      nil
+    end
+
+    # Every normalized key a make answers to (name, slug, published aliases,
+    # built-in aliases) — the haystack for #fuzzy_make. Built once.
+    def fuzzy_keys
+      @fuzzy_keys ||= begin
+        keys = @index.to_a
+        BUILTIN_ALIASES.each { |key, slug| keys << [key, @by_slug[slug]] if @by_slug[slug] }
+        keys.reject { |k, _m| k.empty? }.freeze
+      end
+    end
+
     def region_match?(region)
       Vehicles.normalize(@region) == "global" ||
         Vehicles.normalize(region) == Vehicles.normalize(@region)

data/lib/vehicles/fuzzy.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Vehicles
+  # Typo tolerance for make lookups (0.7.8): bounded Levenshtein distance,
+  # stdlib only. "marcedes" → Mercedes-Benz, "volkswagon" → Volkswagen.
+  #
+  # Deliberately conservative — a confident WRONG make is worse than none:
+  #   - queries under MIN_LENGTH characters never fuzzy-match;
+  #   - the edit budget is 1 for 4-5 characters and 2 from 6 up (never more);
+  #   - the answer must be UNIQUE: if two different makes tie at the best
+  #     distance, the result is nil ("acra": one edit from Acura AND Acma);
+  #   - a candidate may never have FEWER words than the query: deleting a
+  #     whole word is how a make prefix swallows a model token ("volvo v" is
+  #     two edits from "volvo", which turned "Volvo V 60" into Volvo 60);
+  #   - every word keeps its first letter (word for word when the counts
+  #     match, else the first letter of the query): typos rarely hit the
+  #     first letter, model tokens almost always differ there ("citroen e"
+  #     is two edits from "citroen ds" — that is the e-C3, not Citroën DS).
+  module Fuzzy
+    MIN_LENGTH = 4
+
+    module_function
+
+    # Only HUMAN-typed names are fuzzy-matched. Anything shaped like an id, a
+    # path or a slug — any "/" ("car/mercedes-benz/c-class", "/makes/marcedes",
+    # "marcedes-benz/c-class") or all-lowercase hyphenated ("marcedes-benz") —
+    # is machine input: it must resolve exactly or not at all, never to a
+    # guessed make (web routing and API ids rely on it; web-session ruling).
+    # Symbols are always machine input; so is anything with / _ + or a
+    # backslash, a leading/trailing/double hyphen, or a single-case
+    # hyphenated token ("marcedes-benz", "MARCEDES-BENZ"). Mixed case
+    # ("Marcedes-Benz") and plain words ("marcedes") are human. Verifier
+    # finding (0.7.8): each of those machine shapes fuzzed for every typo.
+    def eligible_input?(raw)
+      return false if raw.is_a?(Symbol)
+
+      s = raw.to_s.strip
+      return false if s.match?(%r{[/_+\\]}) || s.start_with?("-") || s.end_with?("-") || s.include?("--")
+
+      !s.match?(/\A[a-z0-9]+(?:-[a-z0-9]+)+\z/) && !s.match?(/\A[A-Z0-9]+(?:-[A-Z0-9]+)+\z/)
+    end
+
+    # Maximum edit distance allowed for a query of this many characters.
+    def budget(length)
+      length >= 6 ? 2 : 1
+    end
+
+    # The single Make closest to `query` among `keys` ([[normalized key, Make],
+    # …]), or nil when nothing is within budget or two makes tie.
+    def unique_closest(query, keys)
+      return nil if query.length < MIN_LENGTH
+
+      limit = budget(query.length)
+      words = query.count(" ") + 1
+      best = limit + 1
+      hits = {}
+      keys.each do |key, make|
+        next if (key.length - query.length).abs > limit # cannot be within budget
+        next if key.count(" ") + 1 < words              # would swallow a word
+        next unless initials_match?(query, key)
+
+        dist = distance(query, key, limit)
+        # `distance` reports out-of-budget as limit + 1, the same value `best`
+        # starts at — test the LIMIT, or a lone length-compatible key would be
+        # accepted at any distance (codex review, 0.7.8: "z" * 28 → a make).
+        next if dist > limit || dist > best
+
+        hits = {} if dist < best
+        best = dist
+        hits[make.slug] = make
+      end
+      hits.size == 1 ? hits.values.first : nil
+    end
+
+    # First letters agree: word for word when both have the same number of
+    # words, otherwise (the query has fewer words, "delorean" vs
+    # "de lorean") just the first letter.
+    def initials_match?(query, key)
+      qw = query.split
+      kw = key.split
+      return qw.first[0] == kw.first[0] unless qw.size == kw.size
+
+      qw.zip(kw).all? { |q, k| q[0] == k[0] }
+    end
+
+    # Edit distance (optimal string alignment: Levenshtein plus adjacent
+    # transposition = 1 edit, so "telsa" is ONE edit from "tesla" — plain
+    # Levenshtein counted it as two and let the one-substitution "temsa" win).
+    # Gives up early: returns `limit + 1` once two consecutive rows exceed
+    # `limit` (a transposition reads two rows back, so one row is not enough).
+    def distance(left, right, limit)
+      prev2 = nil
+      prev = (0..right.length).to_a
+      left.each_char.with_index(1) do |lch, row|
+        cur = [row]
+        right.each_char.with_index(1) do |rch, col|
+          swap = prev2 && col > 1 && lch == right[col - 2] && left[row - 2] == rch
+          cur << cell(prev, cur, col, lch == rch, swap ? prev2[col - 2] : nil)
+        end
+        return limit + 1 if cur.min > limit && prev.min > limit
+
+        prev2 = prev
+        prev = cur
+      end
+      [prev.last, limit + 1].min
+    end
+
+    # One DP cell: deletion, insertion, substitution, and — when the two
+    # characters are swapped neighbours — transposition from two rows back.
+    def cell(prev, cur, col, same, swap_from)
+      best = [prev[col] + 1, cur[col - 1] + 1, prev[col - 1] + (same ? 0 : 1)].min
+      swap_from ? [best, swap_from + 1].min : best
+    end
+  end
+end

data/lib/vehicles/http.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Vehicles
+  # The one way this gem talks to a VehiclesDB server: a single GET, capped by
+  # `config.api_timeout`, never retried, never raising. Shared by the hosted
+  # images provider (keyed, JSON) and the plate templates (public, SVG), so
+  # the latency promise and the no-silent-retry rule live in one place.
+  module HTTP
+    module_function
+
+    # `config.api_base_url` + path + query. Plain concatenation, not
+    # URI.join: an origin ("http://localhost:3030") and an origin behind a
+    # path prefix ("https://proxy.example/vdb") both keep everything they say.
+    def url(path, params = {})
+      # Lazy-required: the gem is standalone-first, and a key-less install
+      # that renders no plates never touches the network.
+      require "uri"
+
+      uri = URI("#{Vehicles.configuration.api_base_url.to_s.chomp("/")}#{path}")
+      uri.query = URI.encode_www_form(params) unless params.empty?
+      uri
+    end
+
+    # The response body of a 2xx, or nil on ANY failure (network, timeout,
+    # non-2xx). Callers treat nil as "fall back".
+    def get(uri, headers = {})
+      require "net/http"
+
+      config = Vehicles.configuration
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = config.api_timeout
+      http.read_timeout = config.api_timeout
+      # Net::HTTP silently re-sends an idempotent GET once after a read
+      # timeout. That would double the latency we promise to cap AND bill a
+      # served image twice, so one request means one request.
+      http.max_retries = 0
+
+      request = Net::HTTP::Get.new(uri)
+      headers.each { |name, value| request[name] = value }
+      response = http.request(request)
+      response.body if response.is_a?(Net::HTTPSuccess)
+    rescue StandardError => e
+      warn "[vehicles] request to VehiclesDB failed (#{e.class}); falling back" if $DEBUG
+      nil
+    end
+  end
+end

data/lib/vehicles/make.rb

@@ -9,6 +9,10 @@ module Vehicles
   #   make.models     # => ["A3", "A4", "Q3", ...]
   #   make.model("a3")# => #<Vehicles::Model "Audi A3">
   class Make
+    # "Serie 3" — how BMW sells the 3 Series in Spain and Italy (and "Série"
+    # in France, which normalizes the same) — read as "3 Series".
+    LOCALIZED_SERIES = /\Aserie (\w+)\z/
+
     attr_reader :name, :slug, :aliases, :kinds
 
     def initialize(attrs)
@@ -58,15 +62,26 @@ module Vehicles
       models(**filters).map { |m| [m.name, m.model_slug] }
     end
 
-    # Find one model within this make by exact (normalized) name or slug.
-    # "a3" / "A3" / "Q 3" resolve; partial input does NOT (so `model("a")`
-    # returns nil, not "A3" — important, since the vehicle_model validator relies
-    # on this). Fuzzy/partial matching lives in `Vehicles.search`.
-    def model(query)
+    # Find one model within this make by name or slug. Forgiving about case,
+    # accents and spacing — "a3", "A 3", "XCeed" (the dataset's "X Ceed") and
+    # BMW's Spanish "Serie 3" (→ "3 Series") all resolve — but partial input
+    # does NOT (so `model("a")` returns nil, not "A3" — important, since the
+    # vehicle_model validator relies on this). Fuzzy/partial matching lives in
+    # `Vehicles.search`.
+    #
+    # Some names exist as several kinds (Toyota "Land Cruiser" is a car, a
+    # van, a truck and a bus). Without `kind:` the car wins — it's what people
+    # mean — and pass `kind:` to pick another:
+    #   toyota.model("Land Cruiser")              # => the car
+    #   toyota.model("Land Cruiser", kind: :bus)  # => the bus
+    def model(query, kind: nil)
       q = Vehicles.normalize(query)
       return nil if q.empty?
 
-      models.find { |m| Vehicles.normalize(m.name) == q || m.model_slug == q }
+      pool = models(kind: kind)
+      series = q.sub(LOCALIZED_SERIES, '\\1 series')
+      matches = named(pool, q) || (named(pool, series) unless series == q)
+      matches && (matches.find(&:car?) || matches.first)
     end
 
     def to_h
@@ -89,5 +104,20 @@ module Vehicles
     def inspect
       %(#<Vehicles::Make "#{name}">)
     end
+
+    private
+
+    # The models answering to a normalized query: by exact name or slug; failing
+    # that, by the same letters and digits with spacing ignored ("xceed" is
+    # "X Ceed", "a 5" is "A5") — but only when that lands on ONE name, never a
+    # guess between two. nil when nothing answers.
+    def named(pool, query)
+      exact = pool.select { |m| Vehicles.normalize(m.name) == query || m.model_slug == query }
+      return exact if exact.any?
+
+      squeezed = query.delete(" ")
+      loose = pool.select { |m| Vehicles.normalize(m.name).delete(" ") == squeezed }
+      loose if loose.map { |m| Vehicles.normalize(m.name) }.uniq.one?
+    end
   end
 end

data/lib/vehicles/mcp_server.rb

@@ -162,7 +162,7 @@ module Vehicles
       makes = Vehicles.dataset.makes(kind: kind)
       unless q.strip.empty?
         n = Vehicles.normalize(q)
-        exact = Vehicles.dataset.find_make(q)
+        exact = Vehicles.dataset.find_make(q, fuzzy: false) # MCP tools stay exact (agents pass ids/slugs)
         makes = makes.select { |m| Vehicles.normalize(m.name).include?(n) }
         makes = [exact, *makes].uniq if exact && (kind.nil? || exact.kinds.include?(kind))
       end
@@ -178,8 +178,8 @@ module Vehicles
     end
 
     def get_model(args)
-      m = Vehicles.model(args.fetch("make"), args.fetch("model")) ||
-          Vehicles.find("#{args.fetch("make")} #{args.fetch("model")}")
+      m = Vehicles.model(args.fetch("make"), args.fetch("model"), fuzzy: false) ||
+          Vehicles.find("#{args.fetch("make")} #{args.fetch("model")}", fuzzy: false)
       if m
         model_json(m)
       else
@@ -194,8 +194,8 @@ module Vehicles
       list = Vehicles.dataset.top_models(kind: args["kind"]&.to_sym,
                                          country: args["country"], limit: limit)
       { models: list.map { |m| model_json(m) },
-        note: "Ranked by global popularity decile from official registration counts; " \
-              "country filters by evidenced availability." }
+        note: "Ranked from official registration counts: with a country, by that country's own " \
+              "rank (per kind — pass kind for a clean list); without one, by global popularity decile." }
     end
 
     def model_json(model)

data/lib/vehicles/model.rb

@@ -25,10 +25,10 @@ module Vehicles
     REGIONS = %i[eu na as sa oc af].freeze
 
     attr_reader :make, :make_slug, :name, :kind, :body_type, :global_decile,
-                :availability, :regions, :aliases
+                :availability, :regions, :aliases, :former_ids, :country_ranks, :mass_decile
 
     # @param attrs [Hash] one model entry from the dataset (name/slug/kind +
-    #   optional body_type/global_decile/availability/regions/aliases)
+    #   optional body_type/global_decile/availability/regions/aliases/former_ids)
     # @param make [String] the parent make's display name
     # @param make_slug [String] the parent make's slug (for the composite slug)
     def initialize(attrs, make:, make_slug:)
@@ -51,6 +51,22 @@ module Vehicles
       @regions       = (attrs["regions"] || []).map(&:to_sym).freeze
       # Documented alternate names (nicknames, native scripts, market names).
       @aliases       = (attrs["aliases"] || []).freeze
+      # Full canonical ids ("car/alfa-romeo/159sw") this record absorbed via
+      # the dataset's append-only migration contract (SCHEMA.md: renames
+      # alias, nothing is silently deleted). Empty for never-renamed records.
+      @former_ids    = (attrs["former_ids"] || []).freeze
+      # { "gb" => 2, "nl" => 1, ... } — the model's rank among every model of
+      # its KIND in that country, from official registration counts (dataset
+      # projection key `country_ranks`, data 2026.10+). Empty when unranked or
+      # when the snapshot predates the key; `rank_in` then returns nil.
+      @country_ranks = (attrs["country_ranks"] || {}).freeze
+      # Per-KIND mass decile 1 (heaviest 10% by registrations summed across
+      # measured countries) … 10 — "how many exist", where global_decile
+      # (a presence average) answers "popular in many places". Published from
+      # dataset 2026.10.1 (pipeline#255, ruling R3); nil on older snapshots
+      # (including the bundled 2026.10.0) and for unranked records.
+      pop = attrs["popularity"]
+      @mass_decile = attrs["mass_decile"] || (pop.is_a?(Hash) ? pop["mass_decile"] : nil)
       freeze
     end
 
@@ -86,6 +102,13 @@ module Vehicles
       availability.include?(country.to_s.downcase)
     end
 
+    # Rank in one country among all models of the same kind (1 = most
+    # registered there), or nil when that country has no ranking for it.
+    #   Vehicles.find("vw golf").rank_in(:gb)  # => 2
+    def rank_in(country)
+      country_ranks[country.to_s.downcase]
+    end
+
     # Evidence of presence on a continent (:eu/:na/:sa/:as/:oc/:af):
     #   Vehicles.find("perodua myvi").available_in_region?(:as)  # => true
     def available_in_region?(region)
@@ -126,7 +149,8 @@ module Vehicles
     def to_h
       { make: make, model: name, slug: slug, kind: kind, body_type: body_type,
         global_decile: global_decile, rarity: rarity,
-        availability: availability, regions: regions, aliases: aliases }
+        availability: availability, regions: regions, aliases: aliases,
+        former_ids: former_ids, country_ranks: country_ranks, mass_decile: mass_decile }
     end
 
     # Value-object equality — two models with the same slug are equal.
@@ -159,9 +183,21 @@ module Vehicles
       Vehicles.resolve(:segment, self)
     end
 
-    # Image URL, optionally year-/color-accurate. nil without hosted data.
-    def image(year: nil, color: nil)
-      Vehicles.resolve(:image, self, year: year, color: color)
+    # One rendered image URL, ready for an <img src>. `size` picks the
+    # variant (:sm/:md/:lg), `color` a palette slug (Vehicles.colors); an
+    # un-rendered color falls back honestly server-side rather than erroring.
+    # `year` is accepted for forward-compatibility but not yet served.
+    # nil without hosted data — always render a placeholder path.
+    def image(year: nil, color: nil, size: :md)
+      Vehicles.resolve(:image, self, year: year, color: color, size: size)
+    end
+
+    # The full hosted images payload — every variant with dimensions, the
+    # rendered palette for this model, served-vs-requested color, provenance.
+    # Reach for this when one URL isn't enough (srcset, color pickers,
+    # caching whole responses). nil without hosted data.
+    def images(color: nil)
+      Vehicles.resolve(:images, self, color: color)
     end
   end
 end

data/lib/vehicles/plates/jurisdiction.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Vehicles
+  module Plates
+    # One issuing jurisdiction — a country, or a state where plates are
+    # state-issued ("us-fl"; a bare "us" will never exist). Wraps the raw
+    # dataset YAML: authority, binding (vehicle vs owner), the
+    # jurisdiction-wide charset law, and every series.
+    class Jurisdiction
+      attr_reader :code, :authority_name, :authority_url, :binding, :charset, :series
+
+      def self.load(path)
+        raw = YAML.safe_load_file(path, aliases: true)
+        new(code: File.basename(path, ".yml"), raw: raw)
+      end
+
+      def initialize(code:, raw:)
+        @code           = code
+        @authority_name = raw.dig("authority", "name")
+        @authority_url  = raw.dig("authority", "url")
+        @binding        = raw["binding"]
+        @charset        = (raw["charset_defaults"] || {}).freeze
+        @series         = (raw["series"] || []).map { |entry| Series.new(entry) }
+          .sort_by { |s| [ s.klass == "standard" ? 0 : 1, s.klass, s.period["start"] || 0 ] }.freeze
+        freeze
+      end
+
+      def to_s = code
+      def inspect = %(#<Vehicles::Plates::Jurisdiction #{code} (#{series.size} series)>)
+    end
+  end
+end