# `Emerge`
[🔗](https://github.com/emerge-elixir/emerge/blob/v0.2.1/lib/emerge.ex#L1)

Public API for writing viewport modules.

Use `Emerge` for modules that mount viewport state or options, define UI with
`render/0` or `render/1`, handle input, and request rerenders.

`use Emerge` also brings the common `Emerge.UI` helpers into scope, so
viewport modules can declare trees directly or call regular Elixir functions
that return `Emerge.tree()`.

It also aliases `Emerge` as `Viewport`, which makes callbacks and helper
calls such as `@impl Viewport` and `Viewport.rerender(state)` available
inside the module.

Viewport state is a plain map. Emerge keeps its runtime metadata under the
reserved `:__emerge__` key.

Element event helpers such as `Event.on_press/1`, `Event.on_click/1`, and
`Event.on_swipe_right/1`
deliver regular process messages and are usually handled in `handle_info/2`.
Implement `handle_input/2` when you want to react to raw input events coming
from the renderer.

`use Emerge` stops the viewport by default when Wayland sends a close request.
Override `handle_close/2` to customize that behavior.

For retained-tree diffing, encoding, and event routing helpers, see
`Emerge.Engine`.

# `state`

```elixir
@type state() :: map()
```

Viewport state map passed to render/1 and callback functions.

# `tree`

```elixir
@type tree() :: Emerge.Engine.Element.t()
```

Public tree type built with `Emerge.UI` and rendered by Emerge backends.

# `handle_close`
*optional* 

```elixir
@callback handle_close(term(), state()) :: {:noreply, state()} | {:stop, term(), state()}
```

# `handle_info`
*optional* 

```elixir
@callback handle_info(term(), state()) :: {:noreply, state()} | {:stop, term(), state()}
```

# `handle_input`
*optional* 

```elixir
@callback handle_input(term(), state()) :: {:noreply, state()} | {:stop, term(), state()}
```

# `mount`

```elixir
@callback mount(keyword()) ::
  {:ok, state(), keyword()} | {:ok, keyword()} | {:stop, term()}
```

# `render`
*optional* 

```elixir
@callback render() :: tree()
```

# `render`
*optional* 

```elixir
@callback render(state()) :: tree()
```

# `wrap_payload`
*optional* 

```elixir
@callback wrap_payload(term(), term(), term()) :: term()
```

# `default_wrap_payload`

```elixir
@spec default_wrap_payload(term(), term(), term()) :: term()
```

# `notify_source_reloaded`

```elixir
@spec notify_source_reloaded(term()) :: :ok
```

# `renderer`

```elixir
@spec renderer(pid()) :: term()
```

# `rerender`

```elixir
@spec rerender(state()) :: state()
```

---

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