# `ExRatatui.Runtime`
[🔗](https://github.com/mcass19/ex_ratatui/blob/v0.7.1/lib/ex_ratatui/runtime.ex#L1)

Runtime inspection and trace controls for supervised ExRatatui applications.

`snapshot/1` returns runtime metadata including:

  * `:mode`, `:mod`, and `:transport`
  * `:dimensions` and `:polling_enabled?`
  * `:render_count` and `:last_rendered_at`
  * `:subscription_count` and `:subscriptions`
  * `:active_async_commands`
  * `:trace_enabled?`, `:trace_limit`, and `:trace_events`

`inject_event/2` delivers a synthetic terminal event through the same runtime
transition path as a polled input event. This is useful for deterministic
tests when an app is running under `test_mode`, which intentionally disables
live terminal input polling.

# `disable_trace`

```elixir
@spec disable_trace(GenServer.server()) :: :ok
```

Disables runtime tracing for `server` and clears retained trace events.

# `enable_trace`

```elixir
@spec enable_trace(
  GenServer.server(),
  keyword()
) :: :ok
```

Enables in-memory runtime tracing for `server`.

Once enabled, trace events are collected in memory and can be retrieved with
`trace_events/1`. Each trace event is a map describing a state transition:

    %{
      type: :event | :info | :render | :command | :subscription,
      timestamp: DateTime.t(),
      ...
    }

## Options

  * `:limit` — maximum number of recent trace events to retain in memory.
    Defaults to `200`.

# `inject_event`

```elixir
@spec inject_event(
  GenServer.server(),
  ExRatatui.Event.Key.t()
  | ExRatatui.Event.Mouse.t()
  | ExRatatui.Event.Resize.t()
) :: :ok
```

Injects a synthetic terminal event into `server`.

This follows the same event path as a real polled input event, so it works
for both callback-runtime and reducer-runtime apps. It is primarily useful
under `test_mode`, where live terminal polling is intentionally disabled.

# `snapshot`

```elixir
@spec snapshot(GenServer.server()) :: map()
```

Returns a snapshot of a supervised app's runtime state.

The returned map is intended for debugging, tests, and runtime introspection.
Under `test_mode`, `:polling_enabled?` is `false`, which makes it easy to
assert the server is running headlessly.

The returned map contains:

    %{
      mode: :callbacks | :reducer,
      mod: MyApp.TUI,
      transport: :local | :ssh | :distributed_server,
      polling_enabled?: boolean(),
      dimensions: {width, height},
      render_count: non_neg_integer(),
      last_rendered_at: DateTime.t() | nil,
      trace_enabled?: boolean(),
      trace_limit: pos_integer(),
      trace_events: [map()],
      subscription_count: non_neg_integer(),
      subscriptions: [%{id: term(), kind: atom(), interval_ms: pos_integer(), fired?: boolean(), active?: boolean()}],
      active_async_commands: non_neg_integer()
    }

# `trace_events`

```elixir
@spec trace_events(GenServer.server()) :: [map()]
```

Returns the current trace event list for `server`.

This is shorthand for `snapshot(server).trace_events`.

---

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