@spec cells_payload(GenServer.server()) :: [[list()]]

Converts terminal cells into a JSON-safe nested list.

Cell tuples {grapheme, fg, bg, flags} become [grapheme, fg, bg, flags] where colors are [r, g, b] or nil.

@spec cursor_payload(GenServer.server()) :: map()

Returns JSON-safe cursor metadata for the visible viewport.

@spec handle_focus(boolean()) :: {:ok, binary()} | :none

Encodes a terminal focus change event.

@spec handle_key(GenServer.server(), map()) :: {:ok, binary()} | :none

Converts a browser key event into an encoded terminal escape sequence.

Returns {:ok, binary} or :none for unrecognized keys.

@spec handle_mouse(GenServer.server(), map()) :: {:ok, binary()} | :none

Converts a browser mouse event into an encoded terminal escape sequence.

@spec handle_resize(
  GenServer.server(),
  pos_integer(),
  pos_integer(),
  GenServer.server() | nil
) :: :ok

Resizes the terminal and optional PTY to the given dimensions.

@spec handle_text(GenServer.server(), binary()) :: :ok

Writes committed browser text input to the terminal.

This is intended for paste and IME composition commits.

@spec incremental_render_payload(String.t(), GenServer.server(), list() | nil) ::
  {map(), list()}

Returns an incremental render payload and the current cell baseline.

previous_cells is the baseline returned by the preceding call. The first call and any terminal shape change return a full :cells grid; subsequent calls return only changed :rows.

@spec key_event_from_params(map()) :: Ghostty.KeyEvent.t() | :none

Parses browser key event params into a Ghostty.KeyEvent.

Returns a Ghostty.KeyEvent struct or :none for unrecognized keys.

Examples

key_event_from_params(%{"key" => "Enter"})
#=> %Ghostty.KeyEvent{action: :press, key: :enter}

key_event_from_params(%{"key" => "Dead"})
#=> :none

@spec mouse_event_from_params(map()) :: Ghostty.MouseEvent.t() | :none

Parses browser mouse event params into a Ghostty.MouseEvent.

Returns a Ghostty.MouseEvent struct or :none for invalid events.

@spec mouse_payload(GenServer.server()) :: map()

Returns JSON-safe mouse reporting mode metadata.

@spec push_render(Phoenix.LiveView.Socket.t(), String.t(), GenServer.server()) ::
  Phoenix.LiveView.Socket.t()

Pushes a "ghostty:render" event with the current terminal cells.

The payload includes the element id for multi-terminal filtering.

@spec render_payload(String.t(), GenServer.server()) :: map()

Returns a render payload map for push_event/3.

Includes the component id so the JS hook can filter events when multiple terminals share a LiveView.

Renders a terminal container <div> with the GhosttyTerminal JS hook.

This is a stateless function component. For a stateful LiveComponent that handles key events internally, use Ghostty.LiveTerminal.Component.

Supports global HTML attributes via :rest. Set copy_mode={true} to let primary-button drags select and copy terminal text even while an application has enabled mouse tracking. Ordinary clicks continue to reach the application.

Attributes

• id (:string) (required)
• cols (:integer) - Defaults to 80.
• rows (:integer) - Defaults to 24.
• fit (:boolean) - Defaults to false.
• autofocus (:boolean) - Defaults to false.
• copy_mode (:boolean) - Defaults to false.
• class (:string) - Defaults to "".
• Global attributes are accepted.