Behaviour and GenServer wrapper for a Mob screen.

Each live screen runs in its own Mob.Screen.Server process holding a Mob.Socket. Mob.Router owns them: it holds the navigation state, starts and stops screens, and restarts one that crashes.

That gives you isolation — a buggy handle_event crashes its own screen and the router restarts it without taking down navigation, sibling screens, background services, or the BEAM. The router is not an OTP Supervisor; it restarts screens itself because only it knows where in the navigation a crashed screen sat (see decisions/2026-08-28-screen-processes-and-supervision.md). A restarted screen re-mounts and loses its assigns.

The functions below delegate to Mob.Router; this module is the behaviour your screens implement.

Lifecycle callbacks (mount, render, handle_event, handle_info, terminate) map directly to the GenServer lifecycle, so the BEAM's existing tools (selective receive, monitors, hot code push) work on screens without any Mob-specific scaffolding.

Usage

defmodule MyApp.CounterScreen do
  use Mob.Screen

  def mount(_params, _session, socket) do
    {:ok, Mob.Socket.assign(socket, :count, 0)}
  end

  def render(assigns) do
    %{
      type: :column,
      props: %{},
      children: [
        %{type: :text, props: %{text: "Count: #{assigns.count}"}, children: []}
      ]
    }
  end

  def handle_event("increment", _params, socket) do
    {:noreply, Mob.Socket.assign(socket, :count, socket.assigns.count + 1)}
  end
end

Starting a screen

{:ok, pid} = Mob.Screen.start_link(MyApp.CounterScreen, %{})

Dispatching events

:ok = Mob.Screen.dispatch(pid, "increment", %{})