# `Minga.Keymap`
[🔗](https://github.com/jsmestad/minga/blob/main/lib/minga/keymap.ex#L1)

Keymap domain facade.

Manages key bindings across editor modes, scopes, and filetypes.
Internally backed by a trie data structure (`Keymap.Bindings`) for
prefix-matching key sequences, and an ETS-backed GenServer
(`Keymap.Active`) for live binding state that merges defaults with
user overrides.

External callers use this facade for binding lookups, key resolution,
and runtime rebinding. The `Keymap.Bindings` trie type appears in
specs across mode dispatch and input handling code.

## Server-aware API

Every binding-lookup and runtime-rebinding function takes an optional
`server` argument. When omitted, calls go to the singleton process
registered under the `default_server/0` name. Pass an explicit server
(pid or registered name) to target an isolated instance, e.g. per-test
fixtures or future per-tab keymaps.

# `mode`

```elixir
@type mode() :: :normal | :insert | :visual | :command
```

Supported editor modes.

# `server`

```elixir
@type server() :: GenServer.server()
```

Reference to a Keymap.Active GenServer (registered name or pid).

# `bind`

```elixir
@spec bind(atom() | {atom(), atom()}, String.t(), atom(), String.t()) ::
  :ok | {:error, String.t()}
```

Binds a key sequence to a command in the given mode.

# `bind`

```elixir
@spec bind(atom() | {atom(), atom()}, String.t(), atom(), String.t(), keyword()) ::
  :ok | {:error, String.t()}
```

Binds a key sequence with options (e.g., `filetype:`).

# `bind`

```elixir
@spec bind(
  server(),
  atom() | {atom(), atom()},
  String.t(),
  atom(),
  String.t(),
  keyword()
) ::
  :ok | {:error, String.t()}
```

Binds a key sequence on an explicit keymap server.

# `default_bindings`

```elixir
@spec default_bindings() :: [{[Minga.Keymap.Bindings.key()], atom(), String.t()}]
```

Returns all default bindings as a flat list.

# `default_leader_trie`

```elixir
@spec default_leader_trie() :: Minga.Keymap.Bindings.node_t()
```

Returns the default leader trie (before user overrides).

# `default_normal_bindings`

```elixir
@spec default_normal_bindings() :: %{
  required(Minga.Keymap.Bindings.key()) => {atom(), String.t()}
}
```

Returns the default normal-mode single-key bindings.

# `default_server`

```elixir
@spec default_server() :: server()
```

Returns the registered name of the default keymap server.

# `filetype_trie`

```elixir
@spec filetype_trie(server(), atom()) :: Minga.Keymap.Bindings.node_t()
```

Returns the filetype-scoped trie (SPC m bindings).

# `leader_trie`

```elixir
@spec leader_trie(server()) :: Minga.Keymap.Bindings.node_t()
```

Returns the merged leader trie (defaults + user overrides).

# `mode_trie`

```elixir
@spec mode_trie(server(), atom()) :: Minga.Keymap.Bindings.node_t()
```

Returns the mode-specific trie for the given mode.

# `normal_bindings`

```elixir
@spec normal_bindings(server()) :: %{
  required(Minga.Keymap.Bindings.key()) => {atom(), String.t()}
}
```

Returns the merged normal-mode single-key bindings.

# `reset`

```elixir
@spec reset(server()) :: :ok
```

Resets all bindings to defaults (discards user overrides).

# `resolve_binding`

```elixir
@spec resolve_binding(server(), atom(), atom() | nil, Minga.Keymap.Bindings.key()) ::
  {:command, atom()} | :not_found
```

Resolves a key press against a mode's merged bindings.

Checks mode-specific trie first, then normal overrides.
Returns `{:command, atom()}` when a command is found, or `:not_found`.

# `resolve_scoped_key`

```elixir
@spec resolve_scoped_key(
  Minga.Keymap.Scope.scope_name(),
  Minga.Keymap.Scope.vim_state(),
  Minga.Keymap.Bindings.key(),
  keyword()
) :: Minga.Keymap.Scope.resolve_result()
```

Resolves a key press within a scope (e.g., `:editor`, `:agent`, `:file_tree`).

Checks scope-specific bindings first, then falls through to the
scope's fallback chain. Returns `Scope.resolve_result()`:
`{:command, atom()}`, `{:prefix, Bindings.node_t()}`, or `:not_found`.

# `scope_trie`

```elixir
@spec scope_trie(
  server(),
  Minga.Keymap.Scope.scope_name(),
  Minga.Keymap.Scope.vim_state()
) ::
  Minga.Keymap.Bindings.node_t()
```

Returns the scope-specific trie for a given scope and vim state.

# `unbind`

```elixir
@spec unbind(server(), atom(), String.t()) :: :ok | {:error, String.t()}
```

Removes a key binding from a mode.

---

*Consult [api-reference.md](api-reference.md) for complete listing*