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

Disables runtime tracing for server and clears retained trace events.

@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 of the form:

%{
  kind: :message | :render | :command | :subscription,
  at_ms: integer(),
  details: map()
}

Where :at_ms is the monotonic system time in milliseconds at which the event fired, and :details depends on :kind:

• :message — %{source: :event | :info, payload: term()}. Input events from the terminal arrive as source: :event; handle_info/2 messages (timers, PubSub, etc.) as source: :info.

• :render — %{frame: ExRatatui.Frame.t(), widget_count: integer()}.
• :command — either %{kind: :message, message: term()}, %{kind: :after, delay_ms: integer(), message: term()}, or %{kind: :async} for supervised async commands.

• :subscription — %{action: :start | :cancel | :fire, id: term(), kind: atom()}.

Options

• :limit — maximum number of recent trace events to retain in memory. Defaults to 200. Events beyond the limit are dropped oldest-first.

@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.

@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 | :session | :distributed_server,
  polling_enabled?: boolean(),
  dimensions: {width, height},
  render_count: non_neg_integer(),
  last_rendered_at: integer() | 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()
}

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

Returns the current trace event list for server.

This is shorthand for snapshot(server).trace_events.