# `Pote`
[🔗](https://github.com/Lorenzo-SF/pote/blob/2.2.0/lib/pote.ex#L1)

Pote — canonical color types, default palette, and top-level helpers.

This module defines the core color type definitions used throughout the
entire library and provides access to the built-in default color palette.

# `argb`

```elixir
@type argb() ::
  {non_neg_integer(), non_neg_integer(), non_neg_integer(), non_neg_integer()}
```

# `cmyk`

```elixir
@type cmyk() :: {float(), float(), float(), float()}
```

# `color_input`

```elixir
@type color_input() ::
  rgb() | hex() | hsl() | hsv() | cmyk() | xterm256() | atom() | String.t()
```

# `color_output`

```elixir
@type color_output() :: rgb() | nil
```

# `hex`

```elixir
@type hex() :: String.t()
```

# `hsl`

```elixir
@type hsl() :: {float(), float(), float()}
```

# `hsv`

```elixir
@type hsv() :: {float(), float(), float()}
```

# `rgb`

```elixir
@type rgb() :: {non_neg_integer(), non_neg_integer(), non_neg_integer()}
```

# `theme_resolver`

```elixir
@type theme_resolver() :: (String.t() -> {:ok, rgb()} | :not_found)
```

A theme resolver: `(key :: String.t()) -> {:ok, rgb()} | :not_found`.

# `xterm256`

```elixir
@type xterm256() :: 0..255
```

# `color`

```elixir
@spec color(atom()) :: {integer(), integer(), integer()} | nil
```

Returns a specific color by name (alias for get_color/1).

# `color_exists?`

```elixir
@spec color_exists?(atom()) :: boolean()
```

Checks if a color name exists in the default palette.

# `color_names`

```elixir
@spec color_names() :: [atom()]
```

Returns all available color names.

# `default_colors`

```elixir
@spec default_colors() :: map()
```

Returns the default color palette.

# `get_color`

```elixir
@spec get_color(atom()) :: {integer(), integer(), integer()} | nil
```

Looks up a color by atom name. Returns RGB tuple or nil.

# `parse`

```elixir
@spec parse(color_input()) :: {:ok, rgb()} | {:error, term()}
```

Parses any color input to an RGB tuple.

Accepts hex strings (`"#FF0000"`, `"FF0000"`), RGB tuples
(`{255, 0, 0}`), HSL/HSV tuples, atom names (`:red`, `:blue`),
and xterm256 integers (`0..255`).

Delegates to `Pote.Orchestrator.parse_color/1`.

Returns `{:ok, {r, g, b}}` on success, `{:error, reason}` on failure.

# `parse!`

```elixir
@spec parse!(color_input()) :: rgb()
```

Like `parse/1` but raises on error.

# `put_theme_resolver`

```elixir
@spec put_theme_resolver(theme_resolver() | nil | :pop) :: :ok
```

Registers a theme resolver at runtime. Multiple resolvers can coexist
in a stack — `resolve_theme_color/1` walks the stack and returns the
first non-`:not_found` result. Useful when several apps / themes are
loaded side-by-side (e.g. tests for multiple consumers).

Pass `nil` to remove ALL resolvers.
Pass `:pop` to remove the most recently registered one.
Pass `:clear` as an alias for `nil`.

# `resolve_theme_color`

```elixir
@spec resolve_theme_color(String.t() | atom()) :: {:ok, rgb()} | :not_found
```

Resolves a theme key (`"primary"`, `"ternary"`, ...) to an RGB tuple.

Strategy (in order):
  1. The configured theme resolver (via `theme_resolver/0`).
  2. Pote's built-in `@default_colors`.

Returns `{:ok, {r, g, b}}` or `:not_found`.

# `theme_resolver`

```elixir
@spec theme_resolver() :: theme_resolver()
```

Returns a combined theme resolver that walks the registered stack.

The combined resolver tries each registered resolver in order and
returns the first non-`:not_found` result. If no resolver is
registered, returns a default that always yields `:not_found`.

Applications embedding Pote (e.g. `Alaja`) can register their own
resolver to make `"theme:<key>"` lookups consult their theme system:

    # In Alaja's startup:
    Pote.put_theme_resolver(fn key ->
      case Alaja.Config.lookup_theme_color(key) do
        {:ok, rgb} -> {:ok, rgb}
        :error -> :not_found
      end
    end)

Multiple resolvers may be registered; the first one to match wins.
This is the recommended pattern when several apps / themes coexist
(e.g. in tests for multiple consumers).

# `theme_resolvers`

```elixir
@spec theme_resolvers() :: [theme_resolver()]
```

Returns the current list of registered theme resolvers (newest first).

The combined resolver returned by `theme_resolver/0` walks this list
in order until one of them returns `{:ok, _}`.

---

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