vehicles 0.4.1 → 0.8.0

data/lib/vehicles/plates/series.rb

@@ -0,0 +1,291 @@
+# frozen_string_literal: true
+
+module Vehicles
+  module Plates
+    # One registration series: a pattern identity with a period, a class
+    # (standard/taxi/diplomatic/…), categories, sourced design facts, and the
+    # two regexes of the dataset's regex policy — `regex` (recall: the
+    # pattern's own alphabet) and `regex_strict` (validation: the alphabet
+    # the authority actually issues). Validation prefers strict.
+    class Series
+      attr_reader :id, :klass, :categories, :period, :period_evidence,
+        :pattern, :display_pattern, :regex, :regex_strict, :design,
+        :variants, :sources, :notes, :validation_regexp, :lenient_regexp,
+        :issued_regexp, :issued_separators
+
+      def initialize(entry)
+        @id           = entry["id"]
+        @klass        = entry["class"] || "standard"
+        @categories   = Array(entry["categories"]).freeze
+        @period       = (entry["period"] || {}).freeze
+        @period_evidence = entry["period_evidence"]
+        @pattern      = entry.dig("format", "pattern")
+        # "\L" escapes a LITERAL L (vs the any-letter placeholder) —
+        # ca-nb-truck-2003 introduced it; resolved for display and walks.
+        @display_pattern = @pattern&.gsub(/\\(.)/) { $1 }
+        @regex        = entry.dig("format", "regex")
+        @regex_strict = entry.dig("format", "regex_strict")
+        @design       = (entry["design"] || {}).freeze
+        @variants     = Array(entry["variants"]).freeze
+        @sources      = Array(entry["sources"]).freeze
+        @notes        = entry["notes"]
+        # Compiled eagerly — the object is frozen, so no lazy memoization.
+        @validation_regexp = compile(@regex_strict || @regex)
+        @lenient_regexp    = compile(self.class.strip_separators(@regex_strict || @regex))
+        segments, separators = self.class.segment_separators(@regex_strict || @regex)
+        @issued_separators = (separators || []).freeze
+        @issued_regexp = segments && compile("\\A(#{segments.join(')(')})\\z")
+        freeze
+      end
+
+      # A strict-validated series has an authority-alphabet regex twin; a
+      # recall-only series (export/dark-blue catch-alls that accept any
+      # current shape) matches loosely by design. Consumers validating user
+      # input should weight strict hits above recall-only ones — Match does.
+      def strict?
+        !regex_strict.nil?
+      end
+
+      # period_evidence values on which the recorded START is not (or not
+      # provenly) the series' birth — an instrument/consolidation date, an
+      # upper bound, or an unverified secondary (the dataset's own honesty
+      # discipline). The label must not present these as the era. Values
+      # like enabling-instrument / statutory-creation-date /
+      # instrument-dated-both-ends ARE true starts and stay unmarked.
+      INSTRUMENT_DATED_EVIDENCE = %w[
+        instrument-in-force instrument-window
+        instrument-in-force-upper-bound secondary-locator-unverified
+      ].freeze
+
+      # "2000 → today" (open, still issued), "1971–2000", or — when the
+      # start is only an instrument date — "~1999–2000" / "~2000 → today":
+      # the format is documented FROM that year and may be older.
+      # es-provincial's 1999–2000 instrument window over a format that ran
+      # for decades is the case this guards. approximate_start? tells a
+      # consumer to explain the "~".
+      def period_label
+        start = period["start"]
+        start = "~#{start}" if approximate_start?
+        finish = period["end"]
+        finish ? "#{start}–#{finish}" : "#{start} → today"
+      end
+
+      # True when the recorded start is an instrument date, not the series'
+      # birth — the display should read it as "documented from", not "began in".
+      def approximate_start?
+        INSTRUMENT_DATED_EVIDENCE.include?(period_evidence)
+      end
+
+      # Re-print a separator-less serial the way this series formats it.
+      # Primary path: match the serial against the regex SEGMENTED at its
+      # separators (the §2.6/§2.8 separator contract makes segmentation
+      # mechanical) and rejoin the captured groups with the separators the
+      # series actually prints — correct even when groups are
+      # variable-length (ES provincial: M-1234-LA and SE-1234-AB both live
+      # in [A-Z]{1,2}-\d{4}-[A-Z]{1,2}; the old pattern walk sliced
+      # "M1234LA" into "M1-234L-A"). Fallback: the pattern walk, but ONLY
+      # when the serial exactly fills the pattern's slots; otherwise the
+      # serial comes back untouched — unformatted is honest, misplaced
+      # separators are not.
+      def format_serial(serial)
+        return nil if serial.nil?
+
+        # The display pattern is authoritative when the serial fills it
+        # exactly — it knows splits the regex cannot (CC-999-999 over
+        # `\d+[- ]\d+` is ambiguous to a greedy match, unambiguous to the
+        # pattern).
+        slots = display_pattern&.each_char&.count { |ch| ![ "-", " ", "·", "." ].include?(ch) }
+        if slots && serial.length == slots
+          idx = 0
+          out = display_pattern.each_char.with_object(+"") do |ch, str|
+            if [ "-", " ", "·", "." ].include?(ch)
+              str << ch
+            else
+              str << (serial[idx] || "")
+              idx += 1
+            end
+          end
+          return out.freeze
+        end
+
+        # Length mismatch: the pattern is one shape of a variable family —
+        # reconstruct from the regex segmented at its separators instead
+        # (ES provincial: "M1234LA" is M-1234-LA, which the fixed-slot walk
+        # sliced into "M1-234L-A").
+        if issued_regexp && (m = issued_regexp.match(serial)) &&
+            m.captures.size == issued_separators.size + 1
+          return m.captures.each_with_index
+                  .map { |part, i| i.zero? ? part : "#{issued_separators[i - 1]}#{part}" }
+                  .join.freeze
+        end
+
+        # Neither path can know — unformatted is honest, misplaced
+        # separators are not.
+        serial.dup.freeze
+      end
+
+      # Tokens that read as "a separator" when they make up a whole
+      # character class — `[- ]` in the ES consular series is dash-or-space,
+      # i.e. a separator spelled as a class.
+      SEPARATOR_TOKENS = [ " ", "-", "·", ".", '\s', '\-', '\.', '\ ' ].freeze
+
+      # Removing a separator can join two repetitions of the same character
+      # class: `[A-Z0-9]+(?:-[A-Z0-9]+)*` becomes the redundant
+      # `[A-Z0-9]+(?:[A-Z0-9]+)*`. Ruby (3.1+) warns while compiling that shape.
+      # Its language is exactly `[A-Z0-9]+`, whether the trailing group is
+      # optional or repeated, so canonicalize it after the separator walk.
+      REDUNDANT_CHARACTER_CLASS_REPEAT = /(\[[^\]]+\])\+\(\?:\1\+\)[*?]/
+
+      # Split a regex source into its serial SEGMENTS and the separator
+      # character printed between each pair — the reconstruction data behind
+      # format_serial. Same scan as strip_separators (same class-vs-range
+      # discipline; a dropped separator's dangling quantifier goes with it),
+      # but instead of discarding separators it records what each one PRINTS
+      # (`\s` and "\ " print a space; a separator-only class prints its
+      # first token). Returns [segments, separators] with
+      # segments.length == separators.length + 1, or [nil, nil] when the
+      # source is nil, has no separators, or segments in a shape the
+      # reconstruction cannot trust (empty segment, capturing groups that
+      # would shift the positional captures).
+      def self.segment_separators(src)
+        return [ nil, nil ] if src.nil?
+
+        body = src.sub('\A', "").sub('\z', "")
+        segments = [ +"" ]
+        separators = []
+        emit = lambda do |printed|
+          if segments.last.empty? && separators.any?
+            # a run of separators prints once — keep the first
+          else
+            separators << printed
+            segments << +""
+          end
+        end
+
+        chars = body.chars
+        i = 0
+        while i < chars.size
+          ch = chars[i]
+
+          if ch == "\\" && i + 1 < chars.size
+            nxt = chars[i + 1]
+            if [ "s", " " ].include?(nxt)
+              i += 2
+              i += 1 if [ "?", "*" ].include?(chars[i])
+              emit.call(" ")
+            elsif [ "-", "." ].include?(nxt)
+              i += 2
+              i += 1 if [ "?", "*" ].include?(chars[i])
+              emit.call(nxt)
+            else
+              segments.last << ch << nxt
+              i += 2
+            end
+            next
+          end
+
+          if ch == "["
+            closing = i + 1
+            closing += 1 while closing < chars.size && chars[closing] != "]"
+            content = chars[(i + 1)...closing].join
+            tokens = content.scan(/\\.|./m)
+            if tokens.any? && tokens.all? { |t| SEPARATOR_TOKENS.include?(t) }
+              first = tokens.first
+              printed = first.start_with?("\\") ? (first[1] == "s" ? " " : first[1]) : first
+              i = closing + 1
+              i += 1 if [ "?", "*" ].include?(chars[i])
+              emit.call(printed)
+            else
+              segments.last << chars[i..closing].join
+              i = closing + 1
+            end
+            next
+          end
+
+          if [ "-", " ", "·" ].include?(ch)
+            i += 1
+            i += 1 if [ "?", "*" ].include?(chars[i])
+            emit.call(ch)
+          else
+            segments.last << ch
+            i += 1
+          end
+        end
+
+        return [ nil, nil ] if separators.empty?
+        return [ nil, nil ] if segments.any?(&:empty?)
+        # A capturing group inside a segment would shift the positional
+        # captures the reconstruction indexes by — bail to the fallback.
+        return [ nil, nil ] if segments.any? { |s| s.match?(/\((?!\?)/) }
+
+        [ segments, separators ]
+      end
+
+      # Remove separator LITERALS from a regex source, respecting character
+      # classes (the "-" inside [A-Z] is a range, not a separator; a class
+      # composed ONLY of separators, like `[- ]`, is a separator and goes).
+      # A quantifier left dangling by a removed separator ("-?", "[- ]?") is
+      # swallowed with it. Linear scan — regexes in this dataset are simple.
+      def self.strip_separators(src)
+        return nil if src.nil?
+
+        out = +""
+        chars = src.chars
+        i = 0
+        while i < chars.size
+          ch = chars[i]
+
+          if ch == "\\" && i + 1 < chars.size
+            nxt = chars[i + 1]
+            if [ "s", "-", ".", " " ].include?(nxt)
+              i += 2
+              i += 1 if [ "?", "*" ].include?(chars[i]) # optional separator: drop its quantifier too
+            else
+              out << ch << nxt
+              i += 2
+            end
+            next
+          end
+
+          if ch == "["
+            # Copy or drop the WHOLE class span in one decision.
+            closing = i + 1
+            closing += 1 while closing < chars.size && chars[closing] != "]"
+            content = chars[(i + 1)...closing].join
+            tokens = content.scan(/\\.|./m)
+            if tokens.any? && tokens.all? { |t| SEPARATOR_TOKENS.include?(t) }
+              i = closing + 1
+              i += 1 if [ "?", "*" ].include?(chars[i])
+            else
+              out << chars[i..closing].join
+              i = closing + 1
+            end
+            next
+          end
+
+          if [ "-", " ", "·" ].include?(ch)
+            i += 1
+            i += 1 if [ "?", "*" ].include?(chars[i])
+          else
+            out << ch
+            i += 1
+          end
+        end
+        out.gsub(REDUNDANT_CHARACTER_CLASS_REPEAT) { "#{Regexp.last_match(1)}+" }
+      end
+
+      def inspect = %(#<Vehicles::Plates::Series #{id} "#{pattern}">)
+
+      private
+
+      # Bad regex in data must degrade like every other lookup: nil, not raise.
+      def compile(source)
+        return nil if source.nil?
+
+        Regexp.new(source)
+      rescue RegexpError
+        nil
+      end
+    end
+  end
+end

data/lib/vehicles/plates/template_fill.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Vehicles
+  module Plates
+    # The REFERENCE FILLER for VehiclesDB plate templates — the client half of
+    # the privacy-safe template endpoint
+    # (GET /plates/:code/:series_id/template.svg, VehiclesDB PRD-PLATE-ART §9).
+    # A client downloads a template once (it carries nothing personal, so it
+    # caches publicly) and writes the user's registration into it HERE, on its
+    # own machine — a registration is personal data and never travels:
+    #
+    #   svg = Vehicles::Plates::TemplateFill.fill(template_svg, "1234 BCD")
+    #
+    # Moved here from vehiclesdb-web (app/models/plates/template_fill.rb; same logic,
+    # plus shape_of and label:), whose renderer will call `fit_size` /
+    # `recentered_baseline` from this gem
+    # so the fit formula lives once. Deliberately dependency-free (Ruby stdlib
+    # `json` only — no Rails, no ActiveSupport, no XML library). Everything it
+    # needs is in the template's own <metadata id="vdb-template"> block, written
+    # by the VehiclesDB renderer from the same layout pass that renders real
+    # serials:
+    #   slots[]  one per character group: shape slice, compact start offset,
+    #            centre x, baseline, font size, nominal width, max width
+    #   advance  how the renderer prices glyph widths (em at size 1) — so a
+    #            filled group gets the same textLength a server render would
+    #
+    # It VALIDATES before it writes: the registration must have exactly the
+    # template's shape (N = digit, L = letter; separators are free), so a
+    # filled plate never shows characters its layout was not computed for.
+    module TemplateFill
+      class Error < StandardError; end
+
+      # The template metadata schema this filler understands
+      # (`"version"` in the vdb-template block).
+      SCHEMA_VERSION = 1
+      SEPARATORS = "- .·"
+      CLASSES = { "N" => /\A[0-9]\z/, "L" => /\A[A-ZÄÖÜ]\z/ }.freeze
+      METADATA = %r{<metadata id="vdb-template"><!\[CDATA\[(.*?)\]\]></metadata>}m
+
+      # A filled template is meant to be inlined into a host page, i.e. trusted as
+      # HTML. Real templates are inert: shapes, text, and data: URIs for the face
+      # and region art. Anything active or external is refused, here at the fill
+      # boundary as well as wherever a template is fetched. data: payloads are
+      # blanked before the scan (base64 may spell "/onxy=" by chance).
+      ACTIVE_CONTENT = Regexp.union(
+        /<\s*(?:script|foreignObject|iframe|object|embed)\b/i,
+        %r{[\s/"']on[a-z]+\s*=}i, # also <svg/onload=…>, which HTML parsers accept
+        /javascript:/i, /@import/i,
+        /href\s*+=\s*+(?!["']?\s*(?:data:|#))/i, /url\(\s*+(?!["']?\s*(?:data:|#))/i
+      )
+      # Only a data: URI's own alphabet (base64 / percent-encoding) is blanked, so
+      # markup after a bare "data:" is still scanned.
+      DATA_URI = %r{data:[a-z]+/[a-z0-9.+-]+(?:;[a-z0-9=.+-]+)*,[A-Za-z0-9+/=%._~-]*}i
+
+      module_function
+
+      # True when the SVG carries nothing a browser would run or fetch.
+      def inert?(svg)
+        !svg.to_s.gsub(DATA_URI, "data:").match?(ACTIVE_CONTENT)
+      end
+
+      # The filled SVG document. Raises Error when the template is not one or
+      # the registration does not fit its shape. `label:` replaces the whole
+      # accessible name (default: "<Country> plate <REGISTRATION>"), e.g.
+      # "Matrícula 1234 BCD" for a Spanish-language page.
+      def fill(svg, registration, label: nil) # rubocop:disable Metrics/AbcSize -- same logic as the VehiclesDB copy
+        inert?(svg) or raise Error, "template carries active or external content; refusing to fill it"
+        meta = metadata(svg)
+        out = svg.sub(METADATA, "")
+        groups(meta, registration).each do |g|
+          slot = g[:slot]
+          attrs = %( textLength="#{g[:text_length]}")
+          pattern = %r{(<text id="#{Regexp.escape(slot["id"])}"[^>]*?)( lengthAdjust="[^"]*")?></text>}
+          out.match?(pattern) or raise Error, "placeholder #{slot["id"]} missing from the template"
+          out = out.sub(pattern) do
+            head = Regexp.last_match(1)
+            adjust = g[:squeezed] ? %( lengthAdjust="spacingAndGlyphs") : Regexp.last_match(2).to_s
+            head = resized(head, slot, g[:font_size], g[:baseline]) if g[:font_size] != slot["font_size"]
+            "#{head}#{adjust}#{attrs}>#{escape(g[:text])}</text>"
+          end
+        end
+        return out.sub(/aria-label="[^"]*?"/) { %(aria-label="#{escape(label.to_s)}") } if label
+
+        out.sub(/(aria-label="[^"]*?) plate template"/) do
+          %(#{Regexp.last_match(1)} plate #{escape(normalize(registration))}")
+        end
+      end
+
+      # The parsed <metadata> block of a template SVG.
+      def metadata(svg)
+        json = svg.to_s[METADATA, 1] or raise Error, "not a VehiclesDB plate template (no vdb-template metadata)"
+        JSON.parse(json)
+      end
+
+      # The SHAPE of a serial-like text, as the template endpoint takes it:
+      # digits → N, letters → L, separators kept ("1234 BCD" → "NNNN LLL").
+      # Nil when a character fits no class. A shape carries no characters, so
+      # it is the only thing about a registration that may leave the machine.
+      # Pattern escapes ("\9") classify their literal (VehiclesDB's
+      # Plates::Template.shape_of, same rules).
+      def shape_of(text)
+        out = +""
+        chars = text.to_s.upcase.chars
+        while (ch = chars.shift)
+          ch = chars.shift.to_s if ch == "\\"
+          out << case ch
+                 when /\A[0-9]\z/ then "N"
+                 when /\A[A-ZÄÖÜ]\z/ then "L"
+                 when /\A[- .·]\z/ then ch
+                 else return nil
+                 end
+        end
+        out.squeeze(SEPARATORS)
+      end
+
+      # Per slot: the characters it prints and the width they need. Usable on
+      # its own by a client that draws text itself (the JSON template carries
+      # the same metadata).
+      def groups(meta, registration) # rubocop:disable Metrics/AbcSize -- same logic as the VehiclesDB copy
+        chars = compact(normalize(registration)).chars
+        shape = compact(meta.fetch("shape"))
+        unless chars.length == shape.length && chars.each_with_index.all? { |ch, i| CLASSES.fetch(shape[i]).match?(ch) }
+          raise Error, "registration does not have the template's shape #{meta["shape"].inspect} " \
+                       "(N = digit, L = letter); fetch the template for its shape"
+        end
+
+        meta.fetch("slots").map do |slot|
+          source = chars[slot["start"], slot["max_chars"]].dup
+          text = slot["shape"].gsub(/[NL]/) { source.shift }
+          size = slot["font_size"]
+          baseline = slot["baseline"]
+          # A lone run (nothing printed beside it) refits exactly as the
+          # renderer fits a real serial: from its natural size, shrunk only
+          # when the real characters overflow the room.
+          if (refit = slot["refit"])
+            size = refit["size"]
+            natural = text_width(text, size, meta.fetch("advance"))
+            size = fit_size(size, refit["avail"], natural) if natural > refit["avail"]
+            rule = refit["baseline"]
+            baseline = recentered_baseline(rule["origin"], size, rule["per_size"]) if rule
+          end
+          width = text_width(text, size, meta.fetch("advance"))
+          squeezed = width > slot["max_width"]
+          { slot: slot, text: text, squeezed: squeezed, font_size: size, baseline: baseline,
+            text_length: (squeezed ? slot["max_width"] : width).round(1) }
+        end
+      end
+
+      # THE fit rule, shared with VehiclesDB's Plates::SvgRenderer: a run
+      # wider than its room shrinks to 98% of the exact fit.
+      def fit_size(size, room, natural_width) = (size * room / natural_width * 0.98).round(2)
+
+      # The re-centred baseline of a lone run, shared with the renderer.
+      def recentered_baseline(origin, size, per_size) = (origin + (size * per_size)).round(1)
+
+      # A placeholder's size-proportional attributes at a refitted size.
+      def resized(head, slot, size, baseline)
+        head = head.sub(/ y="[^"]*"/, %( y="#{baseline}")).sub(/ font-size="[^"]*"/, %( font-size="#{size}"))
+        if slot["letter_spacing_em"].to_f.positive?
+          head = head.sub(/ letter-spacing="[^"]*"/, %( letter-spacing="#{size * slot["letter_spacing_em"]}"))
+        end
+        if slot["stroke_width_em"]
+          head = head.sub(/ stroke-width="[^"]*"/, %( stroke-width="#{(size * slot["stroke_width_em"]).round(2)}"))
+        end
+        head
+      end
+
+      # The renderer's own width model (SvgRenderer#row_metrics): a uniform
+      # statutory pitch, or per-glyph measured advances with a fallback.
+      def text_width(text, size, advance)
+        return text.length * advance["uniform_em"] * size if advance["uniform_em"]
+
+        table = advance.fetch("em")
+        text.chars.sum { |ch| (table[ch] || advance.fetch("fallback_em")) * size }
+      end
+
+      def normalize(registration) = registration.to_s.strip.upcase
+
+      def compact(text) = text.delete(SEPARATORS)
+
+      def escape(text)
+        text.gsub(/[&<>"']/, "&" => "&amp;", "<" => "&lt;", ">" => "&gt;", '"' => "&quot;", "'" => "&#39;")
+      end
+    end
+  end
+end

data/lib/vehicles/plates/templates.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module Vehicles
+  module Plates
+    # VehiclesDB's real plate art for a registration, WITHOUT sending the
+    # registration anywhere (VehiclesDB PRD-PLATE-ART §9: a plate number is
+    # personal data). The plate is fetched as a BLANK template — the series,
+    # the registration's shape ("NNNN LLL", character classes only) and an
+    # optional region — and filled locally by TemplateFill:
+    #
+    #   Vehicles::Plates.render("1234 BCD", jurisdiction: :es)
+    #   # => "<svg … aria-label=\"Spain plate 1234 BCD\">…</svg>", or nil
+    #
+    #   Vehicles::Plates.template(code: :es, series: "es-national-2000", shape: "NNNN LLL")
+    #   # => the blank template SVG, or nil
+    #
+    # The template route is public: no API key is needed, and none is sent.
+    # Templates are cached (in-process by default; `config.plate_template_cache`
+    # takes any store with read(key) / write(key, value, expires_in:), e.g.
+    # Rails.cache), so a page view costs at most one request per (series,
+    # shape, region) and TTL. Never raises: nil on any failure, so a caller
+    # keeps whatever it drew before.
+    TEMPLATE_PATH = "/plates/%<code>s/%<series>s/template.svg"
+    # A failed fetch is remembered briefly, so an unreachable server costs
+    # one timeout per key per window, not one per page view.
+    TEMPLATE_MISS_TTL = 300
+
+    # Client-side fences, so nothing but a template request can leave: a
+    # shape is N/L classes and separators ("_" is the URL-friendly space),
+    # never characters, and the other inputs are identifiers.
+    TEMPLATE_CODE = /\A[a-z]{2}(?:-[a-z]{2,3})?\z/
+    TEMPLATE_SERIES = /\A[a-z0-9-]+\z/
+    TEMPLATE_SHAPE = /\A[NL]+(?:[- .·_][NL]+)*\z/
+    # A region is a subdivision KEY, never free text, so a registration
+    # passed by mistake cannot leave in it: FR département (75, 2A, 971,
+    # 44-bzh), DE Land / CH canton (two letters), AT Land (one digit).
+    TEMPLATE_REGION = /\A(?:[1-9]|[0-9]{2}|97[1-6]|2[AB]|[A-Z]{2}|[0-9]{2}-[A-Z]{3})\z/i
+    # Inert-template fence: TemplateFill::ACTIVE_CONTENT (also enforced by
+    # TemplateFill.fill itself).
+    TEMPLATE_ACTIVE_CONTENT = TemplateFill::ACTIVE_CONTENT
+
+    module_function
+
+    # The blank template SVG for a series, or nil. `shape:` defaults to the
+    # series' canonical pattern on the server; `region:` picks region art
+    # (FR département, DE/AT Land, CH canton).
+    def template(code:, series:, shape: nil, region: nil)
+      code = code.to_s.downcase
+      series = series.to_s
+      shape = shape&.to_s&.tr(" ", "_")
+      region = region&.to_s
+      return nil unless code.match?(TEMPLATE_CODE) && series.match?(TEMPLATE_SERIES)
+      return nil unless (shape.nil? || shape.match?(TEMPLATE_SHAPE)) && (region.nil? || region.match?(TEMPLATE_REGION))
+
+      key = template_cache_key(code, series, shape, region)
+      cached = cache_read(key)
+      return cached.empty? ? nil : cached if cached.is_a?(String)
+
+      svg = fetch_template(code, series, shape, region)
+      cache_write(key, svg || "", svg ? Vehicles.configuration.plate_template_ttl : TEMPLATE_MISS_TTL)
+      svg
+    rescue StandardError
+      nil
+    end
+
+    # `registration` drawn on its series' real plate, filled locally, or nil
+    # when it cannot be: not a plate of that jurisdiction, more than one
+    # standard series it could be (German districts, Italian eras: we would
+    # rather draw nothing than the wrong plate), or no template. Only the
+    # series, the shape and `region:` are sent. `label:` is the accessible
+    # name (TemplateFill.fill).
+    def render(registration, jurisdiction:, region: nil, label: nil)
+      found = match(registration, jurisdiction: jurisdiction)
+      series = template_series(found) or return nil
+      shape = TemplateFill.shape_of(series.format_serial(found.canon)) or return nil
+      svg = template(code: found.jurisdiction.code, series: series.id, shape: shape, region: region) or return nil
+      TemplateFill.fill(svg, registration, label: label)
+    rescue StandardError
+      nil
+    end
+
+    # The one series a match's plate is drawn as: the only standard-class
+    # series among the hits, else the only hit. Nil when it is ambiguous.
+    def template_series(found)
+      standard = found.series.select { |series| series.klass == "standard" }
+      return standard.first if standard.one?
+
+      found.series.first if found.series.one?
+    end
+
+    def fetch_template(code, series, shape, region)
+      params = { shape: shape, region: region }.compact
+      body = HTTP.get(HTTP.url(format(TEMPLATE_PATH, code: code, series: series), params),
+                      "Accept" => "image/svg+xml")
+      return nil unless body
+
+      # Net::HTTP hands back binary; the template is UTF-8 ("·" separators).
+      svg = body.dup.force_encoding(Encoding::UTF_8)
+      return nil unless svg.valid_encoding?
+      return nil unless TemplateFill.inert?(svg)
+
+      svg if TemplateFill.metadata(svg)["version"] == TemplateFill::SCHEMA_VERSION
+    rescue TemplateFill::Error, JSON::ParserError
+      nil
+    end
+
+    # The filler's schema and the gem version are in the key, so an upgrade
+    # never fills a template it was not written for; the base URL too, so a
+    # development server's templates never answer for production's.
+    def template_cache_key(code, series, shape, region)
+      ["vehicles/plate-template", "v#{TemplateFill::SCHEMA_VERSION}", Vehicles::VERSION,
+       Vehicles.configuration.api_base_url, code, series, shape, region].join("/")
+    end
+
+    def cache_read(key)
+      Vehicles.configuration.plate_template_cache.read(key)
+    rescue StandardError
+      nil
+    end
+
+    def cache_write(key, value, ttl)
+      Vehicles.configuration.plate_template_cache.write(key, value, expires_in: ttl)
+    rescue StandardError
+      nil
+    end
+
+    # The default plate_template_cache: in-process, thread-safe, bounded.
+    class TemplateCache
+      MAX_ENTRIES = 256
+
+      def initialize
+        @entries = {}
+        @lock = Mutex.new
+      end
+
+      def read(key)
+        @lock.synchronize do
+          value, expires_at = @entries[key]
+          next value if expires_at.nil? || expires_at > now
+
+          @entries.delete(key)
+          nil
+        end
+      end
+
+      def write(key, value, expires_in: nil)
+        @lock.synchronize do
+          @entries.delete(key)
+          @entries.shift while @entries.size >= MAX_ENTRIES
+          @entries[key] = [value, expires_in && (now + expires_in.to_f)]
+        end
+        value
+      end
+
+      def clear = @lock.synchronize { @entries.clear }
+
+      private
+
+      def now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+end