feat(moonetui): add the native terminal driver.

Signed-off-by: Leo Cheng (heke1228) <chengkelfan@qq.com>

Author: Lfan-ke

README.md

@@ -29,8 +29,9 @@ Cell buffer, differential ANSI renderer, incremental key parser, layout, widgets
 | `@app` | The widget tree, the focus ring, and the frame loop: poll, parse, dispatch, lay out, compose, diff, write | done |
 | `@driver/node` | Node's terminal: raw mode, a queue the data handler fills, and a frame pump | done |
 | `@driver/web` | A terminal drawn on a canvas: the grid, the escape sequences it understands, key encoding, and in-band resize | done |
+| `@driver/native` | A real terminal through the C library: termios on Unix, virtual terminal mode on Windows | done |
 
-What is left for 0.1.0: the native terminal driver (termios and the Windows console), which is written here but verified in CI, since this machine cannot link it.
+All of 0.1.0 is here. What is deliberately not: the CSS-like style system, scrolling containers, and the thirty-odd widgets beyond the eight below — see AGENTS.md for where the line is.
 
 ## Design
 
@@ -44,7 +45,7 @@ Only four operations ever touch a platform: write, read what is available, set r
 moon add moonbitstack/moonetui
 ```
 
-Two runnable examples: `moon run --target js examples/hello` for a terminal, and `examples/browser/index.html` for the same application drawn on a canvas.
+Three runnable examples of the same application: `moon run --target native examples/tui` on a terminal, `moon run --target js examples/hello` under Node, and `examples/browser/index.html` on a canvas in a browser.
 
 ```moonbit
 let screen = @geom.Size::new(80, 24)

driver/native/moon.pkg

@@ -0,0 +1,16 @@
+// A real terminal, through the C library.
+//
+// Windows and Unix look the same from here: the console is put into virtual
+// terminal mode, which makes it speak the same escape sequences a Unix terminal
+// does, so one parser and one renderer serve both.
+import {
+  "moonbitlang/core/encoding/utf8",
+  "moonbitstack/moonetui/driver",
+  "moonbitstack/moonetui/geom",
+}
+
+supported_targets = "native"
+
+options(
+  "native-stub": [ "tty.c" ],
+)

driver/native/native.mbt

@@ -0,0 +1,133 @@
+// Copyright 2026 Leo Cheng
+// SPDX-License-Identifier: Apache-2.0
+
+///|
+/// The terminal this process was started from.
+pub struct NativeTty {
+  buffer : FixedArray[Byte]
+  scratch : FixedArray[Int]
+  mut started : Bool
+  mut raw : Bool
+}
+
+///|
+/// A driver over the standard streams.
+///
+/// The read buffer is allocated once: a terminal hands over a few bytes at a
+/// time, thousands of times a second, and allocating for each of them would be
+/// the only garbage this library produces per frame.
+pub fn NativeTty::new(buffer_size? : Int = 4096) -> NativeTty {
+  {
+    buffer: FixedArray::make(
+      if buffer_size < 64 {
+        64
+      } else {
+        buffer_size
+      },
+      b'\x00',
+    ),
+    scratch: FixedArray::make(2, 0),
+    started: false,
+    raw: false,
+  }
+}
+
+///|
+pub impl @driver.Driver for NativeTty with fn start(self) {
+  // Raw mode fails when the program is not attached to a terminal — piped into
+  // a file, run from a test harness. That is not an error: the application
+  // still draws, and the output is exactly what a terminal would have shown.
+  self.raw = tty_raw(true) == 0
+  self.started = true
+}
+
+///|
+pub impl @driver.Driver for NativeTty with fn stop(self) {
+  self.started = false
+  if self.raw && tty_raw(false) != 0 {
+    raise @driver.Io("cannot restore the terminal")
+  }
+  self.raw = false
+}
+
+///|
+pub impl @driver.Driver for NativeTty with fn write(self, text) {
+  if !self.started {
+    raise @driver.Io("write before start")
+  }
+  let bytes = @utf8.encode(text[:])
+  if bytes.length() == 0 {
+    return
+  }
+  if tty_write(bytes, bytes.length()) < 0 {
+    raise @driver.Io("cannot write to the terminal")
+  }
+}
+
+///|
+pub impl @driver.Driver for NativeTty with fn flush(_self) {
+  // Writes go straight to the file descriptor, so there is nothing held back.
+}
+
+///|
+pub impl @driver.Driver for NativeTty with fn size(self) {
+  if tty_size(self.scratch) != 0 {
+    // A terminal that will not say how big it is — a pipe, a CI log — still has
+    // to be drawn on, and the classic default is what everything else assumes.
+    return @geom.Size::new(80, 24)
+  }
+  @geom.Size::new(self.scratch[0], self.scratch[1])
+}
+
+///|
+pub impl @driver.Driver for NativeTty with fn poll(self, timeout) {
+  let got = tty_read(self.buffer, self.buffer.length(), timeout)
+  if got < 0 {
+    raise @driver.Io("cannot read from the terminal")
+  }
+  if got == 0 {
+    return b""
+  }
+  Bytes::from_array(self.buffer[0:got])
+}
+
+///|
+pub impl @driver.Driver for NativeTty with fn now(_self) {
+  tty_now()
+}
+
+///|
+/// Whether the terminal is in raw mode. False means the program is not attached
+/// to one, which a caller may want to report rather than discover later.
+pub fn NativeTty::is_raw(self : NativeTty) -> Bool {
+  self.raw
+}
+
+///|
+/// Run an application to completion on the terminal.
+///
+/// A native program can block, so the frame loop is a loop. The browser and
+/// Node drivers cannot, which is why the loop lives here rather than in `app`.
+pub fn run(step : () -> Bool raise) -> Unit raise {
+  while step() {
+
+  }
+}
+
+///|
+extern "C" fn tty_raw(on : Bool) -> Int = "moonetui_tty_raw"
+
+///|
+#borrow(text)
+extern "C" fn tty_write(text : Bytes, len : Int) -> Int = "moonetui_tty_write"
+
+///|
+#borrow(buf)
+extern "C" fn tty_read(buf : FixedArray[Byte], len : Int, timeout : Int) -> Int = "moonetui_tty_read"
+
+///|
+#borrow(out)
+extern "C" fn tty_size(out : FixedArray[Int]) -> Int = "moonetui_tty_size"
+
+///|
+extern "C" fn tty_now() -> Int = "moonetui_tty_now"

driver/native/tty.c

@@ -0,0 +1,188 @@
+// Copyright 2026 Leo Cheng
+// SPDX-License-Identifier: Apache-2.0
+//
+// The five things a terminal UI cannot do without the operating system: switch
+// raw mode, write, read what has arrived, ask for the size, and read a clock.
+// Everything else in moonetui is pure MoonBit.
+
+#include <stdint.h>
+#include <string.h>
+#include <moonbit.h>
+
+#ifdef _WIN32
+
+#include <windows.h>
+
+static DWORD saved_in_mode = 0;
+static DWORD saved_out_mode = 0;
+static int saved = 0;
+
+MOONBIT_FFI_EXPORT
+int32_t moonetui_tty_raw(int32_t on) {
+  HANDLE in = GetStdHandle(STD_INPUT_HANDLE);
+  HANDLE out = GetStdHandle(STD_OUTPUT_HANDLE);
+  if (in == INVALID_HANDLE_VALUE || out == INVALID_HANDLE_VALUE) {
+    return -1;
+  }
+  if (on) {
+    if (!saved) {
+      if (!GetConsoleMode(in, &saved_in_mode) ||
+          !GetConsoleMode(out, &saved_out_mode)) {
+        return -1;
+      }
+      saved = 1;
+    }
+    // Virtual terminal input makes the console send the same escape sequences a
+    // Unix terminal does, which is what lets one parser serve both.
+    DWORD in_mode = saved_in_mode;
+    in_mode &= ~(ENABLE_LINE_INPUT | ENABLE_ECHO_INPUT | ENABLE_PROCESSED_INPUT);
+    in_mode |= ENABLE_VIRTUAL_TERMINAL_INPUT | ENABLE_WINDOW_INPUT;
+    DWORD out_mode = saved_out_mode | ENABLE_VIRTUAL_TERMINAL_PROCESSING |
+                     DISABLE_NEWLINE_AUTO_RETURN;
+    if (!SetConsoleMode(in, in_mode) || !SetConsoleMode(out, out_mode)) {
+      return -1;
+    }
+    return 0;
+  }
+  if (saved) {
+    SetConsoleMode(in, saved_in_mode);
+    SetConsoleMode(out, saved_out_mode);
+  }
+  return 0;
+}
+
+MOONBIT_FFI_EXPORT
+int32_t moonetui_tty_write(const uint8_t *text, int32_t len) {
+  HANDLE out = GetStdHandle(STD_OUTPUT_HANDLE);
+  DWORD written = 0;
+  int32_t at = 0;
+  while (at < len) {
+    if (!WriteFile(out, text + at, (DWORD)(len - at), &written, NULL)) {
+      return -1;
+    }
+    at += (int32_t)written;
+  }
+  return at;
+}
+
+MOONBIT_FFI_EXPORT
+int32_t moonetui_tty_read(uint8_t *buf, int32_t len, int32_t timeout_ms) {
+  HANDLE in = GetStdHandle(STD_INPUT_HANDLE);
+  DWORD ready = WaitForSingleObject(in, (DWORD)(timeout_ms < 0 ? 0 : timeout_ms));
+  if (ready != WAIT_OBJECT_0) {
+    return 0;
+  }
+  DWORD got = 0;
+  if (!ReadFile(in, buf, (DWORD)len, &got, NULL)) {
+    return -1;
+  }
+  return (int32_t)got;
+}
+
+MOONBIT_FFI_EXPORT
+int32_t moonetui_tty_size(int32_t *out) {
+  CONSOLE_SCREEN_BUFFER_INFO info;
+  HANDLE handle = GetStdHandle(STD_OUTPUT_HANDLE);
+  if (!GetConsoleScreenBufferInfo(handle, &info)) {
+    return -1;
+  }
+  out[0] = info.srWindow.Right - info.srWindow.Left + 1;
+  out[1] = info.srWindow.Bottom - info.srWindow.Top + 1;
+  return 0;
+}
+
+MOONBIT_FFI_EXPORT
+int32_t moonetui_tty_now(void) {
+  return (int32_t)(GetTickCount64() & 0x7fffffff);
+}
+
+#else
+
+#include <errno.h>
+#include <poll.h>
+#include <sys/ioctl.h>
+#include <termios.h>
+#include <time.h>
+#include <unistd.h>
+
+static struct termios saved_termios;
+static int saved = 0;
+
+MOONBIT_FFI_EXPORT
+int32_t moonetui_tty_raw(int32_t on) {
+  if (on) {
+    if (!saved) {
+      if (tcgetattr(STDIN_FILENO, &saved_termios) != 0) {
+        return -1;
+      }
+      saved = 1;
+    }
+    struct termios raw = saved_termios;
+    // Characters arrive as they are typed, without echo, and without the
+    // terminal turning any of them into signals or flow control.
+    raw.c_lflag &= ~(ECHO | ICANON | IEXTEN | ISIG);
+    raw.c_iflag &= ~(IXON | IXOFF | ICRNL | INLCR | IGNCR | BRKINT | ISTRIP);
+    raw.c_oflag &= ~(OPOST);
+    raw.c_cc[VMIN] = 0;
+    raw.c_cc[VTIME] = 0;
+    return tcsetattr(STDIN_FILENO, TCSANOW, &raw) == 0 ? 0 : -1;
+  }
+  if (saved) {
+    return tcsetattr(STDIN_FILENO, TCSANOW, &saved_termios) == 0 ? 0 : -1;
+  }
+  return 0;
+}
+
+MOONBIT_FFI_EXPORT
+int32_t moonetui_tty_write(const uint8_t *text, int32_t len) {
+  int32_t at = 0;
+  while (at < len) {
+    ssize_t wrote = write(STDOUT_FILENO, text + at, (size_t)(len - at));
+    if (wrote < 0) {
+      if (errno == EINTR) {
+        continue;
+      }
+      return -1;
+    }
+    at += (int32_t)wrote;
+  }
+  return at;
+}
+
+MOONBIT_FFI_EXPORT
+int32_t moonetui_tty_read(uint8_t *buf, int32_t len, int32_t timeout_ms) {
+  struct pollfd waiting;
+  waiting.fd = STDIN_FILENO;
+  waiting.events = POLLIN;
+  waiting.revents = 0;
+  int ready = poll(&waiting, 1, timeout_ms < 0 ? 0 : timeout_ms);
+  if (ready <= 0) {
+    return 0;
+  }
+  ssize_t got = read(STDIN_FILENO, buf, (size_t)len);
+  if (got < 0) {
+    return errno == EAGAIN || errno == EINTR ? 0 : -1;
+  }
+  return (int32_t)got;
+}
+
+MOONBIT_FFI_EXPORT
+int32_t moonetui_tty_size(int32_t *out) {
+  struct winsize size;
+  if (ioctl(STDOUT_FILENO, TIOCGWINSZ, &size) != 0) {
+    return -1;
+  }
+  out[0] = size.ws_col;
+  out[1] = size.ws_row;
+  return 0;
+}
+
+MOONBIT_FFI_EXPORT
+int32_t moonetui_tty_now(void) {
+  struct timespec now;
+  clock_gettime(CLOCK_MONOTONIC, &now);
+  int64_t ms = (int64_t)now.tv_sec * 1000 + now.tv_nsec / 1000000;
+  return (int32_t)(ms & 0x7fffffff);
+}
+
+#endif