An ExRatatui app running on a raster, driven from the caller's own process.

A session is what RasterExRatatui.Surface wraps: the ExRatatui.CellSession, the app server, the writer that delivers its renders, and the RasterExRatatui.Raster that turns them into pixels. It has no process of its own. A consumer that already owns a process in charge of a panel (a screen manager, a device loop) starts a session in it, folds the session's messages with handle/2, and writes the pixels it gets back however the panel wants.

defmodule Badge.Screen do
  use GenServer

  alias RasterExRatatui.{Raster, Session}

  def init(app) do
    Process.flag(:trap_exit, true)
    raster = Raster.new(size: {400, 300}, format: RasterExRatatui.PixelFormat.Mono)
    {:ok, session} = Session.start(raster, app: app, keep_frame: true)
    {:ok, session}
  end

  def handle_info(msg, session) do
    case Session.handle(session, msg) do
      {:render, _patches, session} ->
        Badge.Display.show(Session.frame(session))
        {:noreply, session}

      {:exit, reason, session} ->
        Badge.Display.show(crash_frame(reason))
        {:noreply, session}

      :unknown ->
        {:noreply, session}
    end
  end

  def terminate(_reason, session), do: Session.stop(session)
end

Lifecycle

1. start/2 creates the cell session for the raster's grid, starts the app server linked to the caller, and returns the session. The caller must trap exits: the app's exit then arrives as an {:EXIT, pid, reason} message that handle/2 turns into {:exit, reason, session} instead of taking the caller down.
2. Every render of the app arrives in the caller's mailbox as {RasterExRatatui.Session, ref, diff}. handle/2 takes that message, every other render of the same session already waiting behind it, folds them into the raster as one, and returns the patches. Renders are never queued up: a slow panel shows fewer, later frames, never every frame later and later.
3. await/2 waits for the first render (or the app's exit) with a timeout, for consumers that want the first frame before they show anything.
4. stop/1 stops the app server, waiting up to shutdown_timeout: for its terminate/2 before killing it, and closes the cell session.

When the app exits, its server closes the cell session on the way out; a consumer that wants the app back starts a new session on the same raster (start(raster(session), opts)) and the new app's first render repaints everything.

Options

start/2 takes:

• :app (required) — the ExRatatui.App module to run
• :app_opts — keyword list passed to the app's mount/1 (or reducer init/1), default []. The session adds surface: to it, a map describing the panel: :size (the physical panel in pixels), :cell_size (the effective cell in pixels), :grid_size (cells), :format, :scale, and :rotate (see RasterExRatatui.Raster's rotation section)
• :keep_frame — keep a full frame of the panel up to date (default false). frame/1 then returns it at no cost, and render/2 applies each patch to it, for panels that only take whole frames
• :shutdown_timeout — milliseconds stop/1 waits for the app server before killing it (default 4_000)

The pieces stay reachable: raster/1 is the current raster (RasterExRatatui.Raster.frame/1 renders what the panel shows), server/1 the app server's pid, and drain/2 and render/2 are the two halves of handle/2, for a consumer that gathers renders and rasterises them on its own schedule.