Run an ExRatatui.App inside a Livebook notebook via xterm.js.

Kino.ExRatatui is a byte-stream transport that pipes the runtime server's rendered ANSI through an xterm.js iframe and forwards keypresses + resize events back.

Example

defmodule Counter do
  use ExRatatui.App
  alias ExRatatui.Event.Key
  alias ExRatatui.Layout.Rect
  alias ExRatatui.Widgets.Paragraph

  def mount(_), do: {:ok, %{n: 0}}

  def render(state, frame) do
    [{%Paragraph{text: "Count: #{state.n}"},
      %Rect{x: 0, y: 0, width: frame.width, height: frame.height}}]
  end

  def handle_event(%Key{code: "+"}, s), do: {:noreply, %{s | n: s.n + 1}}
  def handle_event(%Key{code: "q"}, s), do: {:stop, s}
  def handle_event(_, s),                do: {:noreply, s}
end

Kino.ExRatatui.new(Counter)

Mount options

The second argument to new/2 is a keyword list. Any key not listed under Display options below is forwarded verbatim to ExRatatui.App.mount/1. Use it for per-instance configuration your App reads from its mount opts.

The keys :mod, :name, and :transport are reserved by the runtime and silently overwritten.

Display options

Reserved opts that configure the xterm.js iframe rather than the App. All are optional; defaults preserve the current widget look. Unknown values raise ArgumentError at the call site.

Example:

Kino.ExRatatui.new(Counter,
  # mount opts → App.mount/1
  start: 10,
  # display opts → xterm.js
  theme: %{background: "#0d1117", foreground: "#c9d1d9"},
  font_size: 14,
  height: "600px"
)

Global configuration

Set defaults that apply to every new/2 and frame/2 call in the current Livebook (or your application's runtime) with configure/1:

# In a setup cell, or your application's start/2:
Kino.ExRatatui.configure(
  theme: :livebook,
  font_family: "JetBrains Mono, ui-monospace, monospace",
  font_size: 14
)

Merge order is per-instance opts > configure/1 > module defaults, key by key. Setting theme: globally and then passing theme: %{background: "#000"} per-instance overrides the theme alone — the global font_size still wins for that call. See configure/1 for the full list and the Configuration guide for recipes.

Lifecycle

Each new/2 call spawns a fresh Kino.JS.Live server. The runtime server and ExRatatui.Session are created lazily on the first "resize" event from the iframe so we always start at the correct cell dimensions reported by xterm.js's FitAddon. Re-evaluating the cell (or closing the notebook) tears the runtime server down and starts a new one — no state is preserved across re-evals.

How it plugs into ExRatatui

Implements ExRatatui.Transport as a byte-stream transport, using ExRatatui.Transport.start_server/1 to boot the runtime and ExRatatui.Transport.ByteStream to pump input + resize events. See the Custom Transports guide for the reference shape.

Inline images

The bundled JS hook loads @xterm/addon-image, so ExRatatui.Widgets.Image renders end-to-end in Livebook over Sixel and iTerm2 inline-image protocols. Build images with ExRatatui.Image.new/2 and place them in the widget tree like any other widget — no kino-side configuration is needed. The protocol is picked explicitly at construction time; pass :sixel or :iterm2 (xterm.js does not implement the Kitty graphics protocol). See the Images guide for the full API.