Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,11 @@

## Unreleased

- Add `GPUI.Terminal.surface/1`: an application-owned fixed-cell grid with
raw modifier-bearing keys, committed text/IME, multiline clipboard paste,
native selection/copy, scrollback, and measured cell/viewport events.
No terminal parser, PTY, SSH client, or command-line editor is embedded.

## 0.2.0 - 2026-09-08

### Breaking changes
Expand Down
64 changes: 64 additions & 0 deletions apps/gpui/guides/ui/text-and-editing.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,70 @@ revisioned editable surfaces, see
[Editable text surfaces](editable-text.html). Implementation details remain in
[Editable text internals](editable-text-internals.html).

## Application-owned terminals

`GPUI.Terminal.surface/1` is a fixed-cell display and input boundary, not a
terminal emulator or editable text field. The application owns the escape
parser, retained rows, terminal modes, PTY/SSH lifecycle, and key encoding.
Both vanilla and component-capable hosts implement the `terminal` extension.

```elixir
GPUI.Terminal.surface(%{
id: "console",
label: "Remote console",
columns: 80,
rows: [
[%{text: "ready ", columns: 6, color: {:rgb, 0x80CC90}},
%{text: "界", columns: 2}]
],
cursor_row: 0,
cursor_column: 8,
focus_request: 1,
"phx-keystroke": "terminal-key",
"phx-text": "terminal-text",
"phx-paste": "terminal-paste",
"phx-resize": "terminal-size",
"phx-range": "terminal-visible"
})
```

Rows are ordered oldest first. Runs can combine printable ASCII cells; wide,
combining, or fallback graphemes occupy individual one- or two-column runs.
They can specify foreground/background, normal/bold weight, and normal/italic
style. Every glyph is placed on the measured grid with ligatures disabled.
The cursor is separate paint, never a character in selectable/copied text.
Keep `reset_request` stable across ordinary rerenders and increment it when
replacing the terminal session. It clears native scroll/selection/composition.

Events deliberately separate three input sources:

- `:keystroke`: `%{key: key, control: boolean, alt: boolean, shift: boolean,
platform: boolean, repeat: boolean}` for editing/navigation/control/meta keys.
- `:text`: committed Unicode text. IME preedit remains native and is not sent
to the application until committed. Do not reconstruct a local input line.
- `:paste`: clipboard text with tabs and newlines intact. The application
decides paste confirmation and terminal-mode/bracketed-paste encoding.

Printable keys are not emitted a second time as keystrokes. Platform shortcuts
other than select-all/copy/paste remain application commands. On non-macOS
hosts, Control-Shift-C/V also copy/paste. Native mouse selection copies retained
rows; scrolling and Shift-PageUp/PageDown browse history. Shift-End or typing
returns to the tail. Small trackpad deltas accumulate rather than disappearing.

`:resize` reports `%{columns: integer, rows: integer, cell_width: number,
cell_height: number}` using actual font shaping and viewport dimensions.
Zero-sized hidden surfaces do not request a resize. `:range` optionally reports
the exclusive `{first, last}` visible row range as the ordinary range event map.
Do not estimate font widths or feed hidden geometry to a remote PTY.

Override `font_family` when desired; the defaults are Menlo on macOS, Consolas
on Windows, and DejaVu Sans Mono on other platforms, not the proportional UI font.

The public boundary limits snapshots to 10,000 retained rows, 512 columns,
and 8 MiB of text. These are display bounds, not application scrollback policy.
The native host paints only visible rows; no remote bytes, escape sequence, or
clipboard text is executed by GPUI.

## Rich selectable text

`rich_text/1` renders consumer-produced text and shaping runs without moving
Expand Down
30 changes: 29 additions & 1 deletion apps/gpui/lib/gpui/event.ex
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,11 @@ defmodule GPUI.Event do
defstruct [:type, :window_id, :event, :value, attrs: %{}]

@type type ::
:click
:keystroke
| :text
| :paste
| :resize
| :click
| :command
| :change
| :select
Expand Down Expand Up @@ -57,6 +61,10 @@ defmodule GPUI.Event do
}

@routed_types [
:keystroke,
:text,
:paste,
:resize,
:click,
:command,
:change,
Expand Down Expand Up @@ -200,6 +208,12 @@ defmodule GPUI.Event do
defp normalize_value(type, event) when type in [:keydown, :keyup],
do: require_value(event, &is_binary/1)

defp normalize_value(:keystroke, event), do: require_value(event, &valid_keystroke?/1)
defp normalize_value(:resize, event), do: require_value(event, &valid_terminal_size?/1)

defp normalize_value(type, event) when type in [:text, :paste],
do: require_value(event, &bounded_string?(&1, 1_048_576, true))

defp normalize_value(:range, event), do: require_value(event, &valid_range?/1)
defp normalize_value(:transaction, event), do: require_value(event, &is_map/1)
defp normalize_value(:selection, event), do: require_value(event, &is_list/1)
Expand All @@ -223,6 +237,20 @@ defmodule GPUI.Event do

defp fetch_value(event), do: Map.fetch(event, :value)

defp valid_keystroke?(%{key: key} = value) do
bounded_string?(key, 128, false) and
Enum.all?([:control, :alt, :shift, :platform, :repeat], &is_boolean(Map.get(value, &1)))
end

defp valid_keystroke?(_), do: false

defp valid_terminal_size?(%{columns: cols, rows: rows, cell_width: width, cell_height: height}) do
is_integer(cols) and cols in 1..512 and is_integer(rows) and rows in 1..256 and
finite_number?(width) and width > 0 and finite_number?(height) and height > 0
end

defp valid_terminal_size?(_), do: false

defp valid_change_value?(value) when is_binary(value) or is_boolean(value) or is_nil(value),
do: true

Expand Down
66 changes: 66 additions & 0 deletions apps/gpui/lib/gpui/schema/surfaces.ex
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,72 @@ defmodule GPUI.Schema.Surfaces do
@moduledoc "Neutral specialized surfaces implemented directly with vanilla GPUI."
@behaviour GPUI.Schema.Provider
@components [
%{
__struct__: GPUI.Schema.Component,
tag: :ui_terminal,
kind: :terminal_component,
attrs: [
id: :string,
label: :required_string,
columns: {:default, :positive_integer, 80},
cursor_row: {:default, :non_negative_integer, 0},
cursor_column: {:default, :non_negative_integer, 0},
cursor_visible: {:default, :boolean, true},
font_family: {:default, :string},
font_size: {:default, :positive_number, 14.0},
line_height: {:default, :positive_number, 20.0},
focus_request: {:default, :non_negative_integer, 0},
reset_request: {:default, :non_negative_integer, 0},
disabled: :boolean
],
children: true,
events: [
keystroke: :"phx-keystroke",
text: :"phx-text",
paste: :"phx-paste",
resize: :"phx-resize",
range: :"phx-range"
],
extension: %{
__struct__: GPUI.Schema.Extension,
id: :terminal,
version: 1,
capabilities: [:cell_grid, :raw_keyboard, :committed_text, :clipboard, :cell_geometry]
},
public_hidden_attrs: [],
public_required_attrs: [:id, :label],
public_slots: [],
required_events: [],
stateful: false
},
%{
__struct__: GPUI.Schema.Component,
tag: :ui_terminal_row,
kind: :terminal_row_component,
attrs: [],
children: true,
events: [],
extension: nil,
public_hidden_attrs: [],
public_required_attrs: [],
public_slots: [],
required_events: [],
stateful: false
},
%{
__struct__: GPUI.Schema.Component,
tag: :ui_terminal_cell,
kind: :terminal_cell_component,
attrs: [text: :required_string, columns: {:default, :positive_integer, 1}, italic: :boolean],
children: false,
events: [],
extension: nil,
public_hidden_attrs: [],
public_required_attrs: [:text],
public_slots: [],
required_events: [],
stateful: false
},
%{
__struct__: GPUI.Schema.Component,
attrs: [
Expand Down
100 changes: 100 additions & 0 deletions apps/gpui/lib/gpui/terminal.ex
Original file line number Diff line number Diff line change
@@ -0,0 +1,100 @@
defmodule GPUI.Terminal do
@moduledoc """
A native fixed-cell display and input boundary for application-owned terminals.

GPUI does not parse escape sequences, open a PTY, or edit a remote command line.
Pass retained rows (oldest first), with each run declaring its terminal-column
width. The last visible rows follow the tail until the user scrolls. Mouse
selection and platform copy/paste remain native. `phx-text` emits committed
text, `phx-paste` preserves clipboard newlines, and `phx-keystroke` emits
logical keys with modifiers; do not forward printable keys a second time.

Row runs accept `text`, `columns`, and ordinary text style keys `color`,
`background`, `font_weight`, and `font_style`. Split wide/fallback glyphs into
their own runs to preserve exact grid placement. Cursor coordinates address
retained rows, not pixels. `reset_request` clears selection/scroll on session
changes; `focus_request` requests focus without recreating the surface.
"""
alias GPUI.{Element, Schema}
@max_rows 10_000
@max_columns 512
@max_bytes 8 * 1024 * 1024
@style_keys ~w(color background font_weight font_style)a

@doc "Builds a bounded terminal surface from application-owned cell runs."
@spec surface(map()) :: Element.t()
def surface(assigns) do
{rows, attrs} = Map.pop(assigns, :rows, [])
columns = Map.get(attrs, :columns, 80)

unless is_integer(columns) and columns in 1..@max_columns and
is_list(rows) and length(rows) <= @max_rows do
raise ArgumentError, "terminal allows 1–512 columns and at most 10000 retained rows"
end

children = Enum.map(rows, &row(&1, columns))

bytes =
Enum.reduce(rows, 0, fn runs, size ->
Enum.reduce(runs, size, &(byte_size(&1.text) + &2))
end)

if bytes > @max_bytes, do: raise(ArgumentError, "terminal text exceeds 8 MiB")

attrs =
attrs
|> Schema.apply_defaults(:ui_terminal)
|> Schema.validate_component_assigns!(:ui_terminal)

%Element{type: :ui_terminal, attrs: Map.to_list(attrs), children: children}
end

defp row(runs, columns) when is_list(runs) do
{children, used} =
Enum.map_reduce(runs, 0, fn run, used ->
unless is_map(run), do: raise(ArgumentError, "terminal runs must be maps")
text = Map.get(run, :text)
width = Map.get(run, :columns)

unless is_binary(text) and String.valid?(text) and byte_size(text) <= 65_536 and
not String.match?(text, ~r/[\x00-\x1f\x7f]/u) and
is_integer(width) and width > 0 and used + width <= columns and
((byte_size(text) == width and String.match?(text, ~r/\A[\x20-\x7e]+\z/)) or
(match?({_, ""}, String.next_grapheme(text)) and width in [1, 2])) and
Map.keys(run) -- [:text, :columns | @style_keys] == [] do
raise ArgumentError, "terminal runs require bounded single-line text and column spans"
end

cell = %Element{
type: :ui_terminal_cell,
attrs: [
text: text,
columns: width,
italic: Map.get(run, :font_style) in [:italic, "italic"],
style: cell_style(run)
]
}

{cell, used + width}
end)

_ = used
%Element{type: :ui_terminal_row, children: children}
end

defp row(_, _), do: raise(ArgumentError, "terminal rows must be lists of runs")

defp cell_style(run) do
weight =
case Map.get(run, :font_weight, :normal) do
weight when weight in [:normal, "normal"] -> :normal
weight when weight in [:bold, "bold"] -> :bold
_ -> raise ArgumentError, "terminal font_weight must be normal or bold"
end

unless Map.get(run, :font_style, :normal) in [:normal, "normal", :italic, "italic"],
do: raise(ArgumentError, "terminal font_style must be normal or italic")

run |> Map.take([:color, :background]) |> Map.put(:font_weight, weight) |> Map.to_list()
end
end
2 changes: 2 additions & 0 deletions apps/gpui/mix.exs
Original file line number Diff line number Diff line change
Expand Up @@ -123,6 +123,7 @@ defmodule GPUI.MixProject do
],
"Advanced infrastructure": [GPUI.Session],
Text: [
GPUI.Terminal,
GPUI.Text.Buffer,
GPUI.Text.Position,
GPUI.Text.Range,
Expand Down Expand Up @@ -189,6 +190,7 @@ defmodule GPUI.MixProject do
GPUI.Debug,
GPUI.Dev.Reload,
GPUI.View,
GPUI.Terminal,
GPUI.Text.Buffer,
GPUI.Text.Position,
GPUI.Text.Range,
Expand Down
Loading