vehicles 0.4.1 → 0.8.0

data/lib/vehicles/plates.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Vehicles
+  # License-plate & registration-mark knowledge (the VehiclesDB PRD-PLATES
+  # dataset, bundled offline like everything else in this gem). Ask it two
+  # kinds of question:
+  #
+  #   Vehicles.plates                 # => every Jurisdiction
+  #   Vehicles.plates(:nl)            # => one Jurisdiction (series, charset, authority)
+  #   Vehicles.plate("12-GB-BD", jurisdiction: :nl)   # => Plates::Match
+  #
+  # Matching is TWO-TIER, because humans type plates every way at once:
+  #
+  #   exact   — the input, upcased, matches a series' STRICT regex as-typed
+  #             (separators included): formatted exactly as issued.
+  #   lenient — the input with separators stripped ("1234XYZ", "1234 xyz",
+  #             "1234-XYZ" all collapse to "1234XYZ") matches the same strict
+  #             alphabet with the separators removed. Still the authority's
+  #             real issuing alphabet — only the punctuation is forgiven.
+  #
+  # A lenient-only match carries `suggestion`: the serial re-formatted the
+  # way it appears on the physical plate ("did you mean 1234 XYZ").
+  # Same posture as every lookup in this gem: garbage in => empty result,
+  # never an exception.
+  module Plates
+    DATA_DIR = File.expand_path("../../data/plates", __dir__)
+
+    # What people type between plate groups: space(s), hyphen/en/em dash,
+    # middot, period. Stripped for the lenient tier (and from the strict
+    # regexes to derive their lenient twins).
+    SEPARATORS = /[\s\-–—·.]+/
+
+    module_function
+
+    def jurisdictions
+      @jurisdictions ||= Dir.glob(File.join(DATA_DIR, "*.yml")).sort.map do |path|
+        Jurisdiction.load(path)
+      end
+    end
+
+    def jurisdiction(code)
+      jurisdictions.find { |j| j.code == code.to_s.downcase.tr("_", "-") }
+    end
+
+    def classes
+      @classes ||= YAML.safe_load_file(File.join(DATA_DIR, "_meta", "classes.yml")) || {}
+    end
+
+    # A _decode table by bare name ("at-districts", "jp-office-marks") —
+    # the region/office/use-mark lookups that make plates decodable and
+    # let renderers resolve subregion emblems from a serial. Nil for
+    # unknown names; memoized like everything else here.
+    def decode_table(name)
+      @decode_tables ||= {}
+      @decode_tables[name] ||= begin
+        path = File.join(DATA_DIR, "_decode", "#{name.to_s.tr('_', '-')}.yml")
+        File.exist?(path) ? YAML.safe_load_file(path) : nil
+      end
+    end
+
+    # The matcher behind Vehicles.plate. Unknown jurisdiction => empty Match.
+    def match(input, jurisdiction:)
+      juris = jurisdiction(jurisdiction)
+      typed = input.to_s.upcase.strip
+      canon = typed.gsub(SEPARATORS, "")
+      return Match.new(input: input.to_s, jurisdiction: juris, canon: canon, hits: []) if juris.nil? || canon.empty?
+
+      hits = juris.series.filter_map do |series|
+        next nil unless series.validation_regexp
+
+        exact = series.validation_regexp.match?(typed)
+        lenient = exact || series.lenient_regexp&.match?(canon)
+        Match::Hit.new(series: series, exact: exact) if lenient
+      end
+
+      Match.new(input: input.to_s, jurisdiction: juris, canon: canon, hits: hits)
+    end
+
+    # The answer to "is this a plate, and which series issues it?".
+    class Match
+      Hit = Struct.new(:series, :exact, keyword_init: true) do
+        def exact? = exact
+      end
+
+      attr_reader :input, :jurisdiction, :canon, :hits
+
+      def initialize(input:, jurisdiction:, canon:, hits:)
+        @input = input
+        @jurisdiction = jurisdiction
+        @canon = canon
+        # Exact hits outrank lenient ones, strict-validated series outrank
+        # recall-only catch-alls; series order (standard first) breaks ties.
+        @hits = hits.sort_by { |h| [ h.exact? ? 0 : 1, h.series.strict? ? 0 : 1 ] }.freeze
+        freeze
+      end
+
+      def valid? = hits.any?
+      def exact? = hits.any?(&:exact?)
+
+      # True when at least one hit is a strict-validated series — the strong
+      # signal ("the authority issues this alphabet"), vs a catch-all shape
+      # union like an export plate. Prefer this for user-input validation.
+      def strict? = hits.any? { |h| h.series.strict? }
+
+      def series = hits.map(&:series)
+      def best = hits.first&.series
+
+      # The serial formatted the way the best-matching series prints it on
+      # the physical plate — "1234XYZ" typed, "1234 XYZ" issued.
+      def formatted
+        best&.format_serial(canon)
+      end
+
+      # Only when the user's punctuation was off: the "did you mean" string.
+      def suggestion
+        formatted if valid? && !exact?
+      end
+    end
+  end
+end

data/lib/vehicles/providers/hosted_provider.rb

@@ -4,83 +4,74 @@ require "json"
 
 module Vehicles
   module Providers
-    # Talks to the hosted VehiclesDB API to enrich models with years, images, and
-    # segments. It is STRICTLY OPTIONAL: `available?` is true only when an api_key
-    # is configured, so a key-less install never reaches the network. Every call
-    # is error-isolated — a slow, missing, or failing API yields nil and the
-    # resolver falls back to the local data. Tracking/enrichment must never break
-    # the host app, so this never raises out.
+    # Talks to the hosted VehiclesDB API for vehicle imagery. It is STRICTLY
+    # OPTIONAL: `available?` is true only when an api_key is configured, so a
+    # key-less install never reaches the network. Every call is error-isolated
+    # — a slow, missing, or failing API yields nil and the resolver falls back
+    # to the local data. Enrichment must never break the host app, so this
+    # never raises out.
     #
-    # NOTE: the public VehiclesDB API is not live yet. This is the wired-up seam:
-    # the moment the service ships (and you set `config.api_key`), these methods
-    # light up with zero code changes on the consumer's side. Until then they
-    # safely return nil. Endpoint shape is provisional — see https://vehiclesdb.com.
+    # The images endpoint is LIVE (since 2026-07): mint a key at
+    # https://vehiclesdb.com/settings/api-keys, set `config.api_key`, and
+    # `model.image` / `model.images` answer with rendered vehicle imagery.
+    #
+    # `years` and `segment` are the wired-up seam for enrichment the API does
+    # not serve yet: they answer nil WITHOUT a request (a call to an endpoint
+    # that doesn't exist would only cost latency), so the chain falls through
+    # to the local data. They light up here when the API ships them.
     module HostedProvider
+      # Every VehiclesDB API endpoint lives under this path on
+      # `config.api_base_url` (https://vehiclesdb.com/api/v1/...).
+      API_PREFIX = "/api/v1"
+
       module_function
 
       def available?
         !Vehicles.configuration.api_key.to_s.empty?
       end
 
-      def years(model)
-        data = fetch(model)
-        return nil unless data && data["year_start"]
+      def years(_model)
+        nil
+      end
 
-        (data["year_start"]..data["year_end"]) # year_end may be nil => endless range
+      def segment(_model)
+        nil
       end
 
-      def segment(model)
-        fetch(model)&.dig("segment")&.to_sym
+      # One variant URL — the common "just give me an <img src>" case.
+      # `size` picks from the API's rendered variants (:sm 320×180, :md
+      # 640×360, :lg 1280×720; webp).
+      def image(model, year: nil, color: nil, size: :md)
+        images(model, color: color)&.dig("variants", size.to_s, "url")
       end
 
-      def image(model, year:, color:)
+      # The full images payload for a model — palette, every variant with
+      # dimensions, provenance, and the honest color fallback: `color` is what
+      # the API actually served, `requested_color` what you asked for (a color
+      # that isn't rendered yet falls back rather than 404ing).
+      #
+      # GET /api/v1/vehicles/:kind/:make_slug/:model_slug/images?color=<slug>
+      #
+      # `year`/`trim` filters are RESERVED server-side today (the API 422s on
+      # them by contract, so callers can't silently build on unimplemented
+      # semantics) — which is why `image` accepts `year:` but never sends it:
+      # serving the current rendering beats an error until the filter ships.
+      def images(model, color: nil)
         params = {}
-        params[:year]  = year  if year
-        params[:color] = color if color
-        get("/v1/models/#{model.slug}/image", params)&.dig("url")
+        params[:color] = color.to_s unless color.to_s.empty?
+        get("#{API_PREFIX}/vehicles/#{model.kind}/#{model.make_slug}/#{model.model_slug}/images", params)
       end
 
       # --- internals -----------------------------------------------------------
 
-      # Fetch + memoize the full model payload for this process. Keyed by slug.
-      def fetch(model)
-        @cache ||= {}
-        return @cache[model.slug] if @cache.key?(model.slug)
-
-        @cache[model.slug] = get("/v1/models/#{model.slug}", {})
-      end
-
-      def reset!
-        @cache = {}
-      end
-
-      # Issue a GET and parse JSON. Returns nil on ANY failure (network, timeout,
-      # non-200, bad JSON) — callers treat nil as "fall back to local data".
+      # Issue a keyed GET and parse JSON. Returns nil on ANY failure (network,
+      # timeout, non-200, bad JSON) — callers treat nil as "fall back to local
+      # data". The wire rules (timeout, no retry) are Vehicles::HTTP's.
       def get(path, params)
-        # Lazy-required: the gem is standalone-first, and this whole module is
-        # inert without an api_key, so we don't pay net/http at load time.
-        require "net/http"
-        require "uri"
-
-        config = Vehicles.configuration
-        uri = URI.join(config.api_base_url, path)
-        uri.query = URI.encode_www_form(params) unless params.empty?
-
-        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
-
-        request = Net::HTTP::Get.new(uri)
-        request["Authorization"] = "Bearer #{config.api_key}"
-        request["Accept"] = "application/json"
-
-        response = http.request(request)
-        return nil unless response.is_a?(Net::HTTPSuccess)
-
-        JSON.parse(response.body)
-      rescue StandardError => e
-        warn "[vehicles] hosted lookup failed (#{e.class}); using local data" if $DEBUG
+        body = HTTP.get(HTTP.url(path, params),
+                        "Authorization" => "Bearer #{Vehicles.configuration.api_key}", "Accept" => "application/json")
+        body && JSON.parse(body)
+      rescue StandardError # bad JSON, a malformed api_base_url
         nil
       end
     end

data/lib/vehicles/providers/local_provider.rb

@@ -17,9 +17,10 @@ module Vehicles
       # The bundled snapshot is make/model/kind/body_type only — richer fields
       # come from the hosted API. Returning nil here lets the resolver move on
       # (and ultimately yield nil) instead of raising.
-      def years(_model)               = nil
-      def segment(_model)             = nil
-      def image(_model, year:, color:) = nil
+      def years(_model)                                          = nil
+      def segment(_model)                                        = nil
+      def image(_model, year: nil, color: nil, size: :md)        = nil
+      def images(_model, color: nil)                             = nil
     end
   end
 end

data/lib/vehicles/validators/vehicle_make_validator.rb

@@ -15,7 +15,9 @@ class VehicleMakeValidator < ActiveModel::EachValidator
   def validate_each(record, attribute, value)
     return if value.blank?
     return if options[:allow_other] && Vehicles.other?(value)
-    return if Vehicles.make(value)
+    # Exact-only: a typo must fail validation, not be stored as if it were the
+    # make it resembles (Vehicles.make is typo-tolerant since 0.7.8).
+    return if Vehicles.make(value, fuzzy: false)
 
     record.errors.add(attribute, options[:message] || "is not a recognized vehicle make")
   rescue StandardError => e

data/lib/vehicles/validators/vehicle_model_validator.rb

@@ -20,7 +20,7 @@ class VehicleModelValidator < ActiveModel::EachValidator
 
     make_attribute = options[:make] || :make
     make_value = record.respond_to?(make_attribute) ? record.public_send(make_attribute) : nil
-    make = Vehicles.make(make_value)
+    make = Vehicles.make(make_value, fuzzy: false) # exact, same rule as the make validator
     return if make.nil? # unknown make -> defer to the make validator
     return if make.model(value)
 

data/lib/vehicles/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Vehicles
-  VERSION = "0.4.1"
+  VERSION = "0.8.0"
 end

data/lib/vehicles.rb

@@ -2,14 +2,21 @@
 
 require_relative "vehicles/version"
 require_relative "vehicles/configuration"
+require_relative "vehicles/http"
 require_relative "vehicles/make"
 require_relative "vehicles/model"
 require_relative "vehicles/color"
+require_relative "vehicles/fuzzy"
 require_relative "vehicles/dataset"
 require_relative "vehicles/refresher"
 require_relative "vehicles/providers/local_provider"
 require_relative "vehicles/providers/hosted_provider"
 require_relative "vehicles/other_option"
+require_relative "vehicles/plates"
+require_relative "vehicles/plates/jurisdiction"
+require_relative "vehicles/plates/series"
+require_relative "vehicles/plates/template_fill"
+require_relative "vehicles/plates/templates"
 
 # Car makes & models for your Rails app — dropdowns, search, validation. Bundled
 # data, zero config, no network calls. Standalone first; an SDK for the hosted
@@ -43,7 +50,6 @@ module Vehicles
       @providers = nil
       @data_path = nil
       Dataset.reset!
-      Providers::HostedProvider.reset!
     end
 
     # --- data access ---------------------------------------------------------
@@ -108,20 +114,28 @@ module Vehicles
     #   Vehicles.models("Toyota", include_other: true)  # ... + the "Other" escape hatch
     # With `include_other:`, an unknown make (e.g. the "Other" make itself) yields
     # just `[other_label]`, so a make→model picker never dead-ends.
-    def models(make, kind: nil, body_type: nil, region: nil, rarity: nil, max_decile: nil, include_other: false)
-      names = make(make)&.models(kind: kind, body_type: body_type, region: region || configuration.region,
-                                 rarity: rarity, max_decile: max_decile)&.map(&:name) || []
+    # `fuzzy:` is forwarded to `make` (typo-tolerant by default since 0.7.8).
+    def models(make, kind: nil, body_type: nil, region: nil, rarity: nil, max_decile: nil, include_other: false,
+               fuzzy: true)
+      names = make(make, fuzzy: fuzzy)&.models(kind: kind, body_type: body_type,
+                                               region: region || configuration.region,
+                                               rarity: rarity, max_decile: max_decile)&.map(&:name) || []
       append_other_name(names, include_other)
     end
 
-    # The rich Make object (or nil). Forgiving: name, slug, or alias.
-    def make(query)
-      dataset.find_make(query)
+    # The rich Make object (or nil). Forgiving: name, slug, alias — and, since
+    # 0.7.8, typos: "marcedes" → Mercedes-Benz, "volkswagon" → Volkswagen
+    # (bounded edit distance, only when ONE make is closest; ties → nil).
+    # Pass `fuzzy: false` for exact-only resolution (the validators do).
+    def make(query, fuzzy: true)
+      dataset.find_make(query, fuzzy: fuzzy)
     end
 
     # Resolve a free-text "make + model" string into one Model (or nil).
-    def find(query)
-      dataset.find_model(query)
+    # Exact makes are tried first; a misspelled make is retried with the same
+    # typo tolerance as `make` ("volkswagon golf"). `fuzzy: false` disables it.
+    def find(query, fuzzy: true)
+      dataset.find_model(query, fuzzy: fuzzy)
     end
 
     # Resolve a stored make + model PAIR into a Model (or nil). The structured
@@ -130,9 +144,31 @@ module Vehicles
     # model's metadata (kind, body_type, …) back.
     #   Vehicles.model("Audi", "A3")   # => #<Vehicles::Model "Audi A3">
     #   Vehicles.model("vw", "golf")   # forgiving, like every other lookup
-    def model(make_name, model_name)
-      found = make(make_name)
-      found&.model(model_name)
+    #   Vehicles.model("Kia", "XCeed") # spacing-blind: the dataset's "X Ceed"
+    #   Vehicles.model("BMW", "Serie 1")                 # => BMW 1 Series
+    #   Vehicles.model("Toyota", "Land Cruiser")         # => the car (preferred)
+    #   Vehicles.model("Toyota", "Land Cruiser", kind: :bus)
+    def model(make_name, model_name, fuzzy: true, kind: nil)
+      found = make(make_name, fuzzy: fuzzy)
+      found&.model(model_name, kind: kind)
+    end
+
+    # License plates (the bundled PRD-PLATES dataset). No argument: every
+    # jurisdiction. With a code: that jurisdiction (or nil — forgiving).
+    #   Vehicles.plates          # => [#<Jurisdiction nl …>, …]
+    #   Vehicles.plates(:nl)     # => the Netherlands entry (33 series)
+    def plates(code = nil)
+      code.nil? ? Plates.jurisdictions : Plates.jurisdiction(code)
+    end
+
+    # Validate a typed registration against a jurisdiction's real series.
+    # Two-tier: exact as-issued, else separator-forgiving with a formatting
+    # suggestion. Never raises; unknown jurisdictions yield an empty match.
+    #   Vehicles.plate("12-GB-BD", jurisdiction: :nl).valid?     # => true (exact)
+    #   Vehicles.plate("1234XYZ", jurisdiction: :es).suggestion  # => "1234 XYZ"
+    #   Vehicles.plate("12-AB-CD", jurisdiction: :nl).valid?     # => false (vowel purge)
+    def plate(input, jurisdiction:)
+      Plates.match(input, jurisdiction: jurisdiction)
     end
 
     # Every model matching a query, ranked. => [Vehicles::Model, ...]
@@ -149,8 +185,9 @@ module Vehicles
     # first. Filter by country (ISO alpha-2) or continent (:eu/:as/…).
     #   Vehicles.top_models(kind: :car, country: :nl, limit: 10).map(&:name)
     #   Vehicles.top_models(kind: :motorcycle, region: :as, limit: 10)
-    def top_models(kind: nil, country: nil, region: nil, limit: 20)
-      dataset.top_models(kind: kind, country: country, region: region, limit: limit)
+    #   Vehicles.top_models(kind: :car, by: :mass_decile)  # by registration mass (data 2026.10.1+)
+    def top_models(kind: nil, country: nil, region: nil, limit: 20, by: :global_decile)
+      dataset.top_models(kind: kind, country: country, region: region, limit: limit, by: by)
     end
 
     # A curated slice of models by kind/continent/rarity — the "give me sensible
@@ -198,8 +235,8 @@ module Vehicles
 
     # [[label, value], ...] of a make's models for a Rails `select`. Unknown => [].
     #   Vehicles.model_options("audi", include_other: true)  # ... + [other_label, "other"]
-    def model_options(make, kind: nil, body_type: nil, include_other: false)
-      found = make(make)
+    def model_options(make, kind: nil, body_type: nil, include_other: false, fuzzy: true)
+      found = make(make, fuzzy: fuzzy)
       opts = found ? found.model_options(kind: kind, body_type: body_type) : []
       append_other_option(opts, include_other)
     end

data/rakelib/data_refresh.rake

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "English"
+require "json"
+
+# The bundled dataset refresh (data/vehicles.json), as a task so the
+# provenance step and the country-rank merge can't be forgotten.
+#
+#   rake "data:refresh[v2026.10.0]"   # a published release TAG, never a branch
+#
+# Source: the public data repo at a release tag — dist/vehicles.json (the gem
+# projection) unchanged, EXCEPT that each model gains `country_ranks`
+# ({ "gb" => 2, … }) when the projection does not carry it yet. Those ranks
+# are copied from the SAME tag's catalog/<kind>/models.json
+# (popularity.by_country[cc].rank — open CC-BY data), keyed by the full
+# kind/make/model id, so the merged file is what the pipeline's own projection
+# emits once it ships the key (vehiclesdb-pipeline emit.rb write_dist_json!,
+# 2026-10-10). When the projection DOES carry the key, the task asserts every
+# rank equals the catalog's and aborts on any mismatch. Output formatting is
+# the pipeline's (JSON.pretty_generate + "\n"); stripping `country_ranks`
+# from the output gives back the release file byte for byte.
+module DataRefresh
+  module_function
+
+  def git_show(repo, rev, path)
+    out = IO.popen(["git", "-C", repo, "show", "#{rev}:#{path}"], &:read)
+    abort "missing #{path} at #{rev}" unless $CHILD_STATUS.success?
+    out
+  end
+
+  # "kind/make/model" => { "gb" => 2, … } for every ranked model at the tag.
+  def catalog_ranks(repo, rev, kinds)
+    kinds.each_with_object({}) do |kind, ranks|
+      JSON.parse(git_show(repo, rev, "catalog/#{kind}/models.json")).each do |m|
+        by_country = m.dig("popularity", "by_country") || {}
+        r = by_country.filter_map { |cc, p| [cc, p["rank"]] if p["rank"] }.sort.to_h
+        ranks["#{kind}/#{m["id"]}"] = r unless r.empty?
+      end
+    end
+  end
+
+  # Insert `country_ranks` where the pipeline emits it (right after
+  # global_decile), or assert it when the projection already carries it.
+  # Returns [merged, native] counts.
+  def merge!(dist, ranks)
+    merged = native = 0
+    dist["makes"].each do |mk|
+      mk["models"].each do |m|
+        id = "#{m["kind"]}/#{mk["slug"]}/#{m["slug"]}"
+        want = ranks[id]
+        if m.key?("country_ranks")
+          native += 1
+          abort "country_ranks mismatch for #{id}" unless m["country_ranks"] == want
+        elsif want
+          m.replace(with_ranks(m, want))
+          merged += 1
+        end
+      end
+    end
+    [merged, native]
+  end
+
+  def with_ranks(model, ranks)
+    out = model.each_with_object({}) do |(k, v), h|
+      h[k] = v
+      h["country_ranks"] = ranks if k == "global_decile"
+    end
+    out["country_ranks"] ||= ranks
+    out
+  end
+
+  def provenance(tag, commit, version, merged, native)
+    <<~MD
+      # Bundled vehicles dataset
+
+      `data/vehicles.json` is the public data repo's `dist/vehicles.json`
+      (the gem projection) at a release tag:
+
+      - **Source**: https://github.com/vehiclesdb/vehiclesdb `dist/vehicles.json`
+      - **Tag**: `#{tag}` (commit `#{commit}`), dataset version `#{version}`
+      - **country_ranks**: #{native} model(s) carried it natively; #{merged} merged from
+        the same tag's `catalog/<kind>/models.json` `popularity.by_country[cc].rank`
+      - **License**: CC-BY 4.0 (see the data repo's LICENSE + ATTRIBUTION.md)
+
+      Refresh: `rake "data:refresh[<tag>]"` (this file is generated by it).
+    MD
+  end
+end
+
+namespace :data do
+  desc "Refresh data/vehicles.json from a release tag of the local dataset repo"
+  task :refresh, [:tag] do |_t, args|
+    tag = args[:tag] or abort 'usage: rake "data:refresh[vYYYY.MM.P]" (a release tag)'
+    root = File.expand_path("..", __dir__)
+    repo = File.expand_path(ENV.fetch("VDB_DATA_REPO", "~/GitHub/vehiclesdb"))
+    sh "git", "-C", repo, "fetch", "origin", "--tags", "-q"
+    # refs/tags/ only: a branch name or a bare SHA must not pass for a release.
+    commit = IO.popen(["git", "-C", repo, "rev-parse", "--verify", "-q", "refs/tags/#{tag}^{commit}"], &:read).strip
+    abort "not a release tag: #{tag}" unless $CHILD_STATUS.success? && !commit.empty?
+
+    # Read at the VERIFIED commit, not the tag name (a same-named branch must never win).
+    dist = JSON.parse(DataRefresh.git_show(repo, commit, "dist/vehicles.json"))
+    merged, native = DataRefresh.merge!(dist, DataRefresh.catalog_ranks(repo, commit, dist["kinds"]))
+    File.write("#{root}/data/vehicles.json", "#{JSON.pretty_generate(dist)}\n")
+    File.write("#{root}/data/PROVENANCE-vehicles.md",
+               DataRefresh.provenance(tag, commit, dist["version"], merged, native))
+    puts "data refreshed to #{tag} (#{dist["version"]}): #{merged} merged, #{native} native country_ranks"
+  end
+end

data/rakelib/plates_refresh.rake

@@ -0,0 +1,29 @@
+# The plates-data refresh, as a task so the PROVENANCE step can't be
+# forgotten (it is gem-local; a bare rm+archive deletes it silently —
+# that shipped once in 0.7.4 and broke consumers reading the pin).
+namespace :plates do
+  desc "Refresh data/plates from the local dataset repo's origin/main"
+  task :refresh do
+    root = File.expand_path("..", __dir__)
+    ds = File.expand_path("~/GitHub/vehiclesdb")
+    sh "git -C #{ds} fetch origin -q"
+    rm_rf "#{root}/data/plates"
+    mkdir_p "#{root}/data/plates"
+    sh "git -C #{ds} archive origin/main plates | tar -x --exclude 'plates/_art' -C #{root}/data/"
+    rm_rf "#{root}/data/plates/_art"
+    commit = `git -C #{ds} rev-parse origin/main`.strip
+    File.write("#{root}/data/plates/PROVENANCE.md", <<~MD)
+      # Bundled plates dataset (PRD-PLATES, full corpus)
+
+      Copy of `plates/` from the public data repo (EXCLUDING `_art/`),
+      refreshed on gem releases:
+
+      - **Source**: https://github.com/vehiclesdb/vehiclesdb `plates/`
+      - **Commit**: `#{commit}`
+      - **License**: CC-BY 4.0 (see the data repo's LICENSE + ATTRIBUTION.md)
+
+      Refresh: `rake plates:refresh` (this file is generated by it).
+    MD
+    puts "plates refreshed at #{commit}"
+  end
+end

data/sig/vehicles.rbs

@@ -49,6 +49,24 @@ module Vehicles
     attr_accessor cache_path: String
     attr_accessor use_cache: bool
     attr_accessor refresh_timeout: Integer
+    attr_accessor plate_template_cache: untyped
+    attr_accessor plate_template_ttl: Integer
+  end
+
+  module Plates
+    def self.template: (code: String | Symbol, series: String, ?shape: String?, ?region: String?) -> String?
+    def self.render: (String registration, jurisdiction: String | Symbol, ?region: String?, ?label: String?) -> String?
+
+    module TemplateFill
+      class Error < StandardError
+      end
+
+      SCHEMA_VERSION: Integer
+      def self.fill: (String svg, String registration, ?label: String?) -> String
+      def self.shape_of: (String text) -> String?
+      def self.fit_size: (Numeric size, Numeric room, Numeric natural_width) -> Float
+      def self.recentered_baseline: (Numeric origin, Numeric size, Numeric per_size) -> Float
+    end
   end
 
   class Make