Feature Request: Free Terminal / Raw Passthrough Mode

[javier-godoy]

Summary

The XTerm component is designed around a console oriented interaction model where the client handles line editing and fires a single event when the user presses Enter. This makes it unsuitable for use cases that require a free terminal: one that forwards raw keystrokes directly to the server, letting the server or a connected process control echoing, cursor movement, and line editing, just as a real PTY would.

A purely server side free terminal also introduces a network round trip for every keystroke before the user sees any feedback. Both the functional limitations and the latency implications need to be addressed for this feature to be viable.

---

Problem

The following characteristics of the current component prevent it from being used as a raw terminal:

1. Keystroke buffering. Input is held on the client and only sent to the server when the user presses Enter. Processes that need character by character input cannot function.

2. Key suppression. Arrow keys and Escape are intercepted by the console addon on the client and never reach the server. A process that relies on these keys cannot receive them.

3. No resize notification. There is no server side event when the terminal column or row count changes. A connected process cannot reflow its output.

---

Use Cases

Any scenario where the server or an external process must have full control over the terminal input/output stream, such as running full screen Terminal User Interface applications inside the terminal widget.

---

Latency Considerations

In the console oriented model, the client handles local echo, cursor movement, and line editing immediately. The user sees typed characters appear at once, regardless of network conditions.

In a purely server side free terminal, every keystroke would be sent to the server and the server must write the echoed character back before it appears on screen. On a local network this round trip may be imperceptible (under 5 ms). Over a typical internet connection the round trip latency is 50 to 200 ms or more. At those latencies, typing feels sluggish and unresponsive because the screen lags behind the keyboard.

The following features are therefore candidates for optional client side handling. When enabled, they would execute locally without waiting for a server round trip. When disabled, they would be forwarded to the server as raw data, preserving full transparency.

1. Local echo of printable characters. When the user types a letter or digit, it can appear on screen immediately. This is appropriate when the connected process always echoes input, such as a standard shell in line editing mode.

2. Cursor movement. Arrow key presses that move the cursor left or right within the current line can update the cursor position at once. This is appropriate for processes that use standard readline style editing.

3. Backspace and delete. Erasing a character is a high frequency editing action. Each erase operation stalling on a round trip compounds quickly and makes correcting typos painful.

4. Paste. When the user pastes a block of text, showing it on screen while the data is in flight to the server provides immediate visual confirmation and avoids the appearance of the terminal being frozen.

---

The Core Tension

Client side handling is only safe when the server process behaves as expected. A shell echoes every character you type, so local echo works well. A text editor such as vi controls all output itself and does not want the client to echo anything. The client has no way to know which kind of process it is talking to.

This is why the features above must be opt in. The developer knows what process is on the other end and configures the component accordingly.

---

Proposed Design

Base Feature

A new terminal component should be introduced that forwards all input to the server as raw data without any client side interception. All keys, including arrow keys and Escape, must reach the server unmodified. A resize event must be fired whenever the terminal column or row count changes. This alone resolves all three problems described above and is the correct default for any connected process and any network condition.

Optional Client Side Handling

For higher latency connections, the component should expose opt-in properties to handle specific operations locally without waiting for a server round trip:

• Local echo. Printable characters appear on screen immediately as typed.
• Backspace. Erasing a character updates the display immediately.
• Cursor movement. There are three possible approaches. In a fully raw mode, every arrow key is forwarded to the server as an escape sequence. In a fully client side mode (as the current XTerm component does), all movement including wrap navigation is handled locally. A hybrid approach is also possible: left and right arrow key presses that stay within a single visual row are resolved on the client immediately, while movements that would cross a visual line boundary are forwarded to the server, which has full knowledge of the wrap state. Up and down arrows are always forwarded to the server.
• Paste. Pasted text appears on screen while the data is in flight to the server.

The coupling between these features is asymmetric. Backspace and cursor movement each require local echo to be enabled: when local echo is on the server is in no-echo mode, so without local handling of backspace and cursor movement their effects would never appear on screen. Conversely, local echo can function without backspace or cursor movement — the user simply cannot correct typos or reposition the cursor locally, which is a degraded experience but not incorrect. The dependency therefore flows in one direction: backspace and cursor movement require local echo, but local echo does not strictly require them.