rgame 0.2.0 → 0.3.0

data/lib/rgame/engine/i18n.rb

@@ -1,93 +1,318 @@
 # frozen_string_literal: true
 
 require 'yaml'
+require_relative 'i18n/template'
+require_relative 'i18n/plural'
+require_relative 'i18n/plural_rules'
 
 module RGame
   module Engine
-    # Minimal localization: per-locale translation tables (loaded from YAML or a Hash),
-    # `t(key)` with `%{var}` interpolation and a fallback locale, and a `generation`
-    # counter that ticks whenever the locale changes — so cached UI text knows when to
-    # re-resolve without polling every frame. A global module (like EventDispatcher),
-    # so `t` is reachable anywhere. Pure Ruby; YAML is the only (stdlib) dependency.
+    # Translation tables and the current language, as one global module so a
+    # node can resolve text from its constructor, before it is in any tree.
+    #
+    # Tables are read in Rails' YAML format — the top-level key is the locale,
+    # nested keys below it — and compiled at load into one flat Hash per locale,
+    # keyed by the dotted key, whose values are pre-parsed `%{var}` templates or,
+    # for a key whose nested keys are CLDR plural categories, a set of them.
+    # `generation` moves whenever what a key resolves to may have changed, so
+    # cached text compares one Integer instead of looking anything up.
+    #
+    # `I18n` parses Strings and never opens a file: finding and reading locale
+    # files is the asset manager's job.
     module I18n
+      # Raised for a key no link of the chain has, under `missing = :raise`.
+      class MissingKey < StandardError
+        attr_reader :key, :chain
+
+        def initialize(key, chain)
+          @key = key
+          @chain = chain
+          super("no translation for #{key.inspect} in #{chain.join(', ')}")
+        end
+      end
+
+      # Raised under `missing = :raise` when a `Text` declares other variables
+      # than its translation uses: a placeholder the `Text` does not declare, or
+      # a declared name the translation never prints.
+      class VariableMismatch < StandardError
+        attr_reader :key
+
+        def initialize(key, message)
+          @key = key
+          super("#{key}: #{message}")
+        end
+      end
+
+      MISSING_POLICIES = %i[key raise].freeze
+
       class << self
+        # An Integer that moves on every `load`, every change of locale or
+        # default, every `plural_rule`, and every `reset`.
         attr_reader :generation
 
-        # The locale `t` falls back to when the current locale lacks a key.
-        def default = @fallback
+        attr_reader :locale, :default
+
+        # The locales a key is looked up in, in order: the current locale, each
+        # shorter prefix of it, then the default — `[:'de-AT', :de, :en]`.
+        # Rebuilt when the locale or the default changes, not per lookup.
+        attr_reader :chain
 
+        # What a key no link of the chain has resolves to: `:key` (the start)
+        # shows the key itself, `:raise` raises `MissingKey`, and a callable is
+        # called with the key and the chain and its return value is shown.
+        attr_reader :missing
+
+        # Merges a YAML document in Rails' format into the loaded tables. One
+        # document may hold several locales, and a locale loaded twice is merged
+        # key by key rather than replaced. `source` names the file in errors.
+        def load(yaml, source: nil)
+          merge(YAML.safe_load(yaml, aliases: true, filename: source), source || 'translations')
+        end
+
+        # `load` for a Hash already in memory: `load_hash(en: { menu: { title: 'Menu' } })`.
+        def load_hash(hash) = merge(hash, 'translations')
+
+        # Switches the language. `de_AT`, `'de-at'` and `:'de-AT'` name the same
+        # locale. A locale with no table of its own is allowed and resolves
+        # through its chain, so `:'de-CH'` reads the `de` table.
+        def locale=(locale)
+          locale = normalize(locale)
+          return if locale == @locale
+
+          @locale = locale
+          relink
+        end
+
+        # The last link of every chain, and the locale `choose` falls back to.
         def default=(locale)
-          @fallback = locale.to_sym
+          locale = normalize(locale)
+          return if locale == @default
+
+          @default = locale
+          relink
         end
 
-        def reset
-          @locales = {}
-          @current = :en
-          @fallback = :en
-          @generation = 0
+        # The canonical Symbol for a locale identifier: the language lowercase,
+        # a region uppercase, a script capitalized, joined by hyphens —
+        # `normalize('zh_hant_tw') # => :'zh-Hant-TW'`.
+        def normalize(locale)
+          language, *subtags = locale.to_s.split(/[-_]/)
+          raise ArgumentError, "not a locale: #{locale.inspect}" if language.nil? || language.empty?
+
+          subtags.map! { |subtag| subtag.length == 4 ? subtag.capitalize : subtag.upcase }
+          subtags.unshift(language.downcase).join('-').to_sym
         end
 
-        # Register a locale's translations (nested Hashes allowed). Keys are symbolized
-        # so YAML ("string keys") and inline symbol keys look the same to `t`.
-        def load(locale, translations)
-          @locales[locale.to_sym] = symbolize(translations)
-          self
+        # The first of `preferred` — the player's languages, most wanted first —
+        # that has a table for itself or a shorter prefix of itself, normalized
+        # but not shortened: `choose(['fr-CA', 'de-AT'])` with a `de` table is
+        # `:'de-AT'`. The default when none has.
+        def choose(preferred)
+          preferred.each do |candidate|
+            locale = normalize(candidate)
+            return locale if lineage(locale).any? { |link| @tables.key?(link) }
+          end
+          @default
         end
 
-        def load_file(locale, path)
-          load(locale, YAML.load_file(path))
+        def missing=(policy)
+          unless MISSING_POLICIES.include?(policy) || policy.respond_to?(:call)
+            raise ArgumentError, "missing must be :key, :raise or a callable, not #{policy.inspect}"
+          end
+
+          @missing = policy
         end
 
-        def locale = @current
+        # The keys the default locale has that no table in `locale`'s own chain
+        # does, in the default table's order. A key `locale` gets from a parent
+        # (`de-AT` from `de`) is not missing; one it would get only from the
+        # default is.
+        def missing_keys(locale)
+          links = lineage(normalize(locale))
+          defaults = @tables.fetch(@default, {}).keys
+          defaults.reject { |key| links.any? { |link| @tables[link]&.key?(key) } }
+        end
 
-        # Switching the locale bumps the generation so observers re-resolve their text.
-        def locale=(locale)
-          locale = locale.to_sym
-          return if locale == @current
+        # Sets how `language` (or a regional locale, which then wins over its
+        # language) sorts a count into a plural category. The block receives
+        # the count and returns one of `Plural::CATEGORIES`. Replaces a built-in
+        # rule; lasts until `reset`.
+        def plural_rule(language, &rule)
+          raise ArgumentError, 'plural_rule needs a block' unless rule
 
-          @current = locale
+          @plural_rules[normalize(language)] = rule
+          @rule_for.clear
           @generation += 1
+          self
         end
 
-        def available = @locales.keys
+        # The locales that have a table, in load order.
+        def available = @tables.keys
 
-        # Resolve a dotted key ("menu.title" or :menu_title) in the current locale, then
-        # the fallback locale, then the key itself; interpolate %{var} from `vars`.
-        #
-        # Pass `count:` to pluralize: the key's value is then a table of forms
-        # ({ one:, other:, optionally zero: }), and `count` is also exposed to
-        # interpolation as %{count}. English/German use the one/other rule.
-        def t(key, count: nil, **vars)
-          value = lookup(@current, key) || lookup(@fallback, key)
-          value = pluralize(value, count) if count && value.is_a?(Hash)
-          return key.to_s unless value.is_a?(String)
+        # The translation of `key` (or `scope.key`) with `vars` interpolated. A
+        # pluralized key needs `count:`, and picks its form by the plural rule
+        # of the table that supplied it, which is not always the current locale.
+        # Allocates on every call: it is for code off the per-frame path.
+        def t(key, scope: nil, **vars)
+          key = scope ? "#{scope}.#{key}" : key.to_s
+          template = lookup(key)
+          return answer_missing(key) unless template
 
-          vars = vars.merge(count: count) if count
-          vars.empty? ? value : (value % vars)
+          template = pluralize(key, template, vars) if template.is_a?(Plural)
+
+          missing = template.names.find { |name| !vars.key?(name) }
+          raise ArgumentError, "#{key} needs %{#{missing}}" if missing
+
+          template.render(vars)
+        end
+
+        # What a `Text` declaring `names` shows for the dotted `key`, with `vars`
+        # — a Hash holding exactly those names — interpolated. It differs from
+        # `t` in one way: a translation whose placeholders are not the declared
+        # names is a bug in the table or the code, and the missing policy
+        # answers it, raising `VariableMismatch` under `:raise`.
+        def render(key, names, vars)
+          entry = lookup(key)
+          return answer_missing(key) unless entry
+
+          problem = mismatch(entry, names)
+          return answer_mismatch(key, problem) if problem
+
+          entry = pluralize(key, entry, vars) if entry.is_a?(Plural)
+          entry.render(vars)
+        end
+
+        # Forgets every table and plural rule added, and restores the starting
+        # locale and default, `:en`, and the `:key` missing policy. The
+        # generation moves rather than restarting, so text cached before a
+        # reset never mistakes itself for current.
+        def reset
+          @tables = {}
+          @sources = {}
+          @locale = :en
+          @default = :en
+          @generation = (@generation || 0) + 1
+          @chain = chain_for(@locale)
+          @plural_rules = PluralRules::BUILT_IN.dup
+          @rule_for = {}
+          @missing = :key
         end
 
         private
 
-        def pluralize(forms, count)
-          return forms[:zero] if count.zero? && forms.key?(:zero)
+        def relink
+          @chain = chain_for(@locale)
+          @generation += 1
+        end
+
+        def chain_for(locale) = (lineage(locale) << @default).uniq.freeze
+
+        def lineage(locale)
+          subtags = locale.name.split('-')
+          subtags.size.downto(1).map { |length| subtags.first(length).join('-').to_sym }
+        end
+
+        def answer_missing(key)
+          case @missing
+          when :key then key
+          when :raise then raise MissingKey.new(key, @chain)
+          else @missing.call(key, @chain)
+          end
+        end
+
+        def mismatch(entry, names)
+          undeclared = entry.names.find { |name| !names.include?(name) }
+          if undeclared == :count && entry.is_a?(Plural)
+            'is pluralized, and the Text does not declare :count'
+          elsif undeclared
+            "uses %{#{undeclared}}, which the Text does not declare"
+          elsif (unused = names.find { |name| !entry.names.include?(name) })
+            "never uses :#{unused}, which the Text declares"
+          end
+        end
+
+        def answer_mismatch(key, problem)
+          case @missing
+          when :key then key
+          when :raise then raise VariableMismatch.new(key, problem)
+          else @missing.call(key, @chain)
+          end
+        end
+
+        def pluralize(key, plural, vars)
+          raise ArgumentError, "#{key} is pluralized and needs count:" unless vars.key?(:count)
+
+          count = vars[:count]
+          plural.template_for(count, plural_category(plural.locale, count))
+        end
+
+        def plural_category(locale, count)
+          rule = @rule_for[locale] ||= begin
+            language = lineage(locale).find { |link| @plural_rules.key?(link) }
+            @plural_rules.fetch(language, PluralRules::DEFAULT)
+          end
+          rule.call(count)
+        end
 
-          forms[count == 1 ? :one : :other] || forms[:other]
+        def lookup(key)
+          @chain.each do |link|
+            entry = @tables[link]&.[](key)
+            return entry if entry
+          end
+          nil
         end
 
-        def lookup(locale, key)
-          node = @locales[locale]
-          key.to_s.split('.').each do |segment|
-            return nil unless node.is_a?(Hash)
+        def merge(hash, source)
+          raise ArgumentError, "#{source}: expected a Hash of locales" unless hash.is_a?(Hash)
+
+          hash.each do |locale, entries|
+            raise ArgumentError, "#{source}: #{locale} must hold a Hash of keys" unless entries.is_a?(Hash)
+
+            locale = normalize(locale)
+            @sources[locale] = deep_merge(@sources.fetch(locale, {}), stringify(entries, locale.to_s, source))
+            @tables[locale] = compile(@sources[locale], locale)
+          end
+          @generation += 1
+          self
+        end
 
-            node = node[segment.to_sym]
+        def stringify(entries, path, source)
+          entries.to_h do |name, value|
+            name = scalar_name(name, path, source)
+            here = "#{path}.#{name}"
+            [name, value.is_a?(Hash) ? stringify(value, here, source) : scalar_value(value, here, source)]
           end
-          node
         end
 
-        def symbolize(value)
-          return value unless value.is_a?(Hash)
+        def scalar_name(name, path, source)
+          return name.to_s if name.is_a?(String) || name.is_a?(Symbol) || name.is_a?(Integer)
 
-          value.to_h { |k, v| [k.to_sym, symbolize(v)] }
+          raise ArgumentError, "#{source}: #{path} has the key #{name.inspect}; " \
+                               'YAML reads yes/no/on/off/true/false/~ unquoted, so quote it'
+        end
+
+        def scalar_value(value, path, source)
+          return value.to_s if value.is_a?(String) || value.is_a?(Numeric)
+
+          raise ArgumentError, "#{source}: #{path} is #{value.inspect}, not text; " \
+                               'quote it if it is meant as a string'
+        end
+
+        def deep_merge(into, from)
+          into.merge(from) do |_name, old, new|
+            old.is_a?(Hash) && new.is_a?(Hash) ? deep_merge(old, new) : new
+          end
+        end
+
+        def compile(entries, locale, prefix = nil, table = {})
+          entries.each do |name, value|
+            key = prefix ? "#{prefix}.#{name}" : name
+            if !value.is_a?(Hash) then table[key.freeze] = Template.compile(value)
+            elsif Plural.forms?(value) then table[key.freeze] = Plural.new(locale, value)
+            else compile(value, locale, key, table)
+            end
+          end
+          prefix ? table : table.freeze
         end
       end
 

data/lib/rgame/engine/input/action_mapper.rb

@@ -17,10 +17,6 @@ module RGame
     # `down?(physical_id, device:)` and `axis(axis_id, device:)` — a spec passes
     # a fake and a game passes RGame::Core::Input.
     class ActionMapper
-      # A resting analog stick genuinely reports small non-zero values, so
-      # something has to ignore them. Here rather than in the game, because it
-      # is a property of the device, and here rather than in Core, because how
-      # much to ignore is a judgement rather than a fact about the hardware.
       DEAD_ZONE = 0.15
 
       attr_reader :map, :actions
@@ -31,10 +27,6 @@ module RGame
         @device = device
         @dead_zone = dead_zone
 
-        # One reusable snapshot: there is exactly one input state per tick per
-        # player, so these are mutated in place each poll instead of allocated.
-        # Seeded from the map's action list, so the hashes are warm before the
-        # first poll and steady-state polling allocates nothing at all.
         @held = {}
         @prev_held = {}
         @axes = {}
@@ -47,8 +39,6 @@ module RGame
       end
 
       def poll(backend)
-        # Snapshot this frame's held state as "previous" before recomputing it
-        # (in-place copy: no allocation, the keys already exist).
         @held.each { |name, down| @prev_held[name] = down }
 
         return rest if @device.nil?
@@ -63,11 +53,6 @@ module RGame
 
       private
 
-      # A player with no device — an empty seat waiting for a controller — reads
-      # as nothing held and every axis centred. Returning the snapshot rather
-      # than refusing to poll is what lets a game show "press a button to join"
-      # with no special case, and it releases anything that was held when the
-      # controller was unplugged mid-press.
       def rest
         @held.each_key { |name| @held[name] = false }
         @axes.each_key { |name| @axes[name] = 0.0 }
@@ -79,11 +64,6 @@ module RGame
         ids.any? { |id| backend.down?(id, device: @device) }
       end
 
-      # A digital axis and an analog one can both be bound to the same action —
-      # arrows *and* the left stick — so the larger deflection wins. That needs
-      # no per-device branching: a keyboard reads 0.0 for every axis and a stick
-      # reads 0.0 for every key, so whichever device the player is on, the other
-      # source contributes nothing.
       # hot-path
       def axis_value(backend, binding)
         digital = digital_axis(backend, binding)
@@ -93,9 +73,6 @@ module RGame
         digital.abs >= analog.abs ? digital : analog
       end
 
-      # The largest deflection across every pair bound to this axis. Several
-      # pairs is how the arrows, WASD and a d-pad all drive one action; a device
-      # with only one of them reads 0.0 for the rest, so the others cost nothing.
       # hot-path
       def digital_axis(backend, binding)
         pairs = binding.pairs
@@ -110,9 +87,6 @@ module RGame
         best
       end
 
-      # Rescaled rather than merely cut off, so the value ramps from zero as the
-      # stick leaves the dead zone. Cutting off alone makes it jump to the dead
-      # zone's width the moment it starts reading, which is a visible twitch.
       # hot-path
       def dead_zoned(value)
         magnitude = value.abs

data/lib/rgame/engine/input/actions.rb

@@ -53,6 +53,8 @@ module RGame
       # `node.control(actions)` keep working unchanged — a tree with nobody
       # claiming ownership, or a spec that has only one player in mind, passes
       # the snapshot itself where a Players registry would otherwise go.
+      #
+      # @api private
       # hot-path
       def actions_for(_player) = self
 
@@ -81,18 +83,10 @@ module RGame
 
       private
 
-      # A block rather than `fetch(name)`'s bare KeyError, for a message that
-      # says what to do about it. The block only runs on a miss, so the reading
-      # path stays one hash lookup with nothing allocated.
       def undeclared(name)
         raise KeyError, "no such action #{name.inspect} — declare it in the InputMap " \
                         "(this snapshot has #{declared.inspect})"
       end
-
-      # `prev_held` is read with a default on purpose. It is one frame behind, so
-      # on the very first poll after an action is added it legitimately has no
-      # entry, and "was not held before" is the right answer rather than an
-      # error. The current-frame lookup above is what catches a typo.
     end
   end
 end

data/lib/rgame/engine/input/input_map.rb

@@ -67,27 +67,21 @@ module RGame
 
       SOURCES = %i[buttons axis stick].freeze
 
-      # The universal set, merged into every map unless the game overrides it.
-      #
-      # The UI package navigates and activates through these, so a control can
-      # rely on them existing for *every* player without a game having declared
-      # them. They are prefixed rather than plain (`ui_up`, not `up`) so a game
-      # is free to use `:up` for something of its own.
-      #
-      # `ui_cancel` is Escape, which is why RGame::Game's quit key is F2: the
-      # button a player expects to back out of a menu belongs to the menu.
       UI = {
         ui_up: { buttons: [Controls::KEY_UP, Controls::PAD_DPAD_UP] },
         ui_down: { buttons: [Controls::KEY_DOWN, Controls::PAD_DPAD_DOWN] },
         ui_left: { buttons: [Controls::KEY_LEFT, Controls::PAD_DPAD_LEFT] },
         ui_right: { buttons: [Controls::KEY_RIGHT, Controls::PAD_DPAD_RIGHT] },
         ui_confirm: { buttons: [Controls::KEY_RETURN, Controls::KEY_SPACE, Controls::PAD_A] },
-        ui_cancel: { buttons: [Controls::KEY_ESCAPE, Controls::PAD_B] }
+        ui_cancel: { buttons: [Controls::KEY_ESCAPE, Controls::PAD_B] },
+        ui_radial_x: { axis: [[Controls::KEY_LEFT, Controls::KEY_RIGHT],
+                              [Controls::PAD_DPAD_LEFT, Controls::PAD_DPAD_RIGHT]],
+                       stick: Controls::AXIS_LEFT_X },
+        ui_radial_y: { axis: [[Controls::KEY_UP, Controls::KEY_DOWN],
+                              [Controls::PAD_DPAD_UP, Controls::PAD_DPAD_DOWN]],
+                       stick: Controls::AXIS_LEFT_Y }
       }.freeze
 
-      # A playable starting point: eight-way movement on the arrows or the left
-      # stick, and a fire button. A game that wants exactly this declares
-      # nothing at all.
       DEFAULT_ACTIONS = {
         move_x: { axis: [[Controls::KEY_LEFT, Controls::KEY_RIGHT],
                          [Controls::KEY_A, Controls::KEY_D],
@@ -120,6 +114,38 @@ module RGame
 
       def actions = @bindings.keys
 
+      # The button bound to `action` that `device` can actually press, or nil.
+      #
+      # This undoes what the section above describes. One entry lists a key and
+      # a pad button together so that polling needs no branch, and that is right
+      # for reading input and wrong for *showing* it: a prompt has to say "press
+      # A" or "press Space", never both, and which one depends on what the
+      # player last touched.
+      #
+      #   map.button_for(:fire, Controls::KEYBOARD)    # => KEY_SPACE
+      #   map.button_for(:fire, Controls.gamepad(0))   # => PAD_A
+      #
+      # The first match wins, so the order an entry lists its ids in is the order
+      # a prompt prefers them — `ui_confirm` names Return before Space, and a
+      # prompt for it says Return.
+      #
+      # Nil for an action nobody bound, for one with no buttons at all (a stick
+      # or a digital axis is not a button and a prompt for one is a different
+      # picture), and for a device kind the entry does not cover. A caller
+      # showing a prompt has to handle that nil either way, because a rebinding
+      # screen can leave an action unbound.
+      #
+      # Allocation-free, so a HUD may call it per frame rather than caching a
+      # string it would then have to invalidate.
+      def button_for(action, device)
+        binding = @bindings[action]
+        buttons = binding&.buttons
+        return nil if buttons.nil?
+
+        pad = Controls.gamepad?(device)
+        buttons.find { |id| Controls.pad_button?(id) == pad }
+      end
+
       # The entries in the shape they were declared in, so a map can be edited
       # and rebuilt (a config screen) or merged.
       def to_h
@@ -134,11 +160,6 @@ module RGame
 
       private
 
-      # Malformed entries raise here rather than reading as "nothing is ever
-      # pressed" for the rest of the program. An action name misspelled at a
-      # *read* site is still silent — see Actions — but one misspelled in the
-      # map is the mistake that is actually easy to make, and this catches it at
-      # construction rather than at the first frame nobody can move.
       def build(name, entry)
         unknown = entry.keys - SOURCES
         raise ArgumentError, "#{name}: unknown source #{unknown.first.inspect}" unless unknown.empty?
@@ -157,9 +178,6 @@ module RGame
         ids.dup.freeze
       end
 
-      # Accepts one `[negative, positive]` pair or a list of them. A bare pair
-      # is the common case and stays readable; a list is what lets the arrows,
-      # WASD and a d-pad all drive one axis.
       def axis_pairs(name, axis)
         return nil if axis.nil?
 

data/lib/rgame/engine/nav_grid.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    # A walkability grid and the searches over it: region labels and A* routes, run in C by a
+    # Util::RouteSearch over a Util::SolidGrid.
+    #
+    # Where TileBlockers answers *what is in the way of a step*, this answers *what is in the
+    # way of a route*: the same fact about the same cells, asked over a graph instead of along
+    # a box's sweep. Components::TileWorld owns both, over one store.
+    #
+    # It is built one of two ways:
+    #
+    # - **`grid:`** — over a SolidGrid it shares. A cell changed in that grid is changed here
+    #   at once, and region labels follow it on the next query with nothing rebuilt. This is
+    #   how a TileWorld builds one, and the way to build one over solidity that will change.
+    # - **`width:`, `height:`, `solid:`** — from a callable, `solid.call(col, row) -> bool`,
+    #   read once per cell into a private grid of its own. Nothing re-reads the callable, so a
+    #   change behind it is never seen.
+    #
+    # Anything else — both, or neither — is an ArgumentError.
+    #
+    # Routes are cells, never pixels. Turning a cell into the point a node must reach depends
+    # on the node's collider, which a grid has no business knowing; Components::Navigator
+    # does that.
+    #
+    # The grid is 8-connected with octile costs (1 straight, √2 diagonal), and a diagonal step
+    # is allowed only when both orthogonal cells beside it are open, so a route never cuts the
+    # corner of a solid cell. Connected regions are labelled whenever the grid has changed
+    # since they last were, which makes an unreachable goal — the answer a search is slowest
+    # to give, because it has to exhaust the region first — a lookup whenever it lies in
+    # another region.
+    #
+    # Coordinates are Integers, and anything else is a TypeError. An Integer outside the
+    # grid, however large, is answered like any cell outside it.
+    #
+    # A search runs on demand, never per frame, and allocates its result; everything else it
+    # keeps is reused between searches. One grid is therefore not safe to search from two
+    # threads at once.
+    class NavGrid
+      def initialize(grid: nil, width: nil, height: nil, solid: nil)
+        @grid = grid ? shared(grid, width, height, solid) : private_grid(width, height, solid)
+        @search = Util::RouteSearch.new(@grid)
+      end
+
+      def width = @grid.width
+      def height = @grid.height
+
+      def walkable?(col, row)
+        !@grid.solid?(col, row) && col >= 0 && row >= 0 && col < @grid.width && row < @grid.height
+      end
+
+      # The connected region containing the cell, as an Integer label — two walkable cells
+      # share a label exactly when a route joins them — or nil for a solid cell or one
+      # outside the grid.
+      def region(col, row) = @search.region(col, row)
+
+      def reachable?(from_col, from_row, to_col, to_row)
+        from = @search.region(from_col, from_row)
+        to = @search.region(to_col, to_row)
+        !from.nil? && from == to
+      end
+
+      # The cheapest route from start to goal, both included, as `[[col, row], ...]` — or
+      # nil when either end is solid, outside the grid, or in another region. Start equal
+      # to goal is a route of one cell. Ties between equally cheap routes are broken the
+      # same way every time, so the same query always returns the same route.
+      def find(from_col, from_row, to_col, to_row) = @search.find(from_col, from_row, to_col, to_row)
+
+      private
+
+      def shared(grid, width, height, solid)
+        return grid unless width || height || solid
+
+        raise ArgumentError, 'a NavGrid is built over a grid: or from width:, height: and solid:, not both'
+      end
+
+      def private_grid(width, height, solid)
+        unless width && height && solid
+          raise ArgumentError, 'a NavGrid needs a grid:, or all of width:, height: and solid:'
+        end
+
+        Util::SolidGrid.build(width, height) { |col, row| solid.call(col, row) }
+      end
+    end
+  end
+end