把终端当成
一块可差分更新的画布

tl;dr

一句话结论

hand-tui = 声明式组件树 + 差分渲染器 + 异步输入流水线。 它不打整屏，只发改动；不接管事件循环，由 tokio 拉动； 组件之间通过 ComponentId、OverlayHandle 等稳定句柄解耦，背后是一套对终端"光标位置"的强不变量约束。

architecture

三层架构：应用 / 运行时 / I/O

逻辑分层很清爽：顶层是你写的组件树，中层是 Tui 运行时（持有组件树、渲染器、监听器、Overlay 栈），底层是终端 I/O 与 stdin 重组。三层间用 trait 解耦，方便测试和换底层。

component model

Component / Focusable / Container

所有 UI 元素都收敛到这三个抽象。render 是"宽 → 行数组"的纯函数， handle_input 返回 Handled 或 Ignored 让父级决定是否冒泡。

pub trait Component: Send {
    /// 渲染：拿到当前可用宽度，吐若干行字符串
    fn render(&self, width: u16) -> Vec<String>;

    /// 输入：默认不处理，返回 Ignored 让父级继续派发
    fn handle_input(&mut self, _: &InputEvent) -> HandleResult {
        HandleResult::Ignored
    }

    fn invalidate(&mut self) {}
    fn wants_key_release(&self) -> bool { false }

    /// 统一的可见性钩子，默认"永远可见"
    fn hide(&mut self) { self.set_hidden(true); }
    fn show(&mut self) { self.set_hidden(false); }
    fn set_hidden(&mut self, _: bool) {}
    fn is_hidden(&self) -> bool { false }
}

关键设计 1：render 是纯函数。 它只看自身状态 + 宽度，不写终端。所有 ANSI 字节最后由 DiffRenderer 一次性发出。这一刀切下去后，组件可以独立 测试（"给定 width=80，应该输出这 3 行"），也可以被 Overlay 合成器拿去 做行级合并。

关键设计 2：handle_input 显式回 Ignored。 冒泡链由 Container::dispatch_to_focused 控制——先丢给 focused 子节点，未消费再倒序遍历其他子节点。这意味着即使最上层的 Toast 弹层在场， 底下的 Editor 也仍然能拿到自己的 Ctrl-S，只要 Toast 不主动消费。

焦点派发的优先级

differential rendering

差分渲染：只发改动那几行

DiffRenderer 是这套框架最值得拿出来讲的地方。它围绕 一个写死的"光标位置不变量"，把"打整屏"压缩到了 "上次帧 vs 这次帧的最小差集"。

diff 算法的四种分支

input pipeline

从字节到 InputEvent 的五段流水线

终端输入是个噪声很大的字节流：SSH 抖一下 F1 就会断成两半， 中文 IME 会触发 CSI 27 u，鼠标滚轮发 SGR 1006。 hand-tui 把这条"字节 → 语义事件"的路切成五段，每段职责单一。

enum InputEvent {
  Key(Key),         // 已识别的语义键
  Raw(String),      // 未分类的原始字节
  Paste(String),    // bracketed paste 合成
  Resize{cols,rows},// SIGWINCH
  Tick,             // 动画/防抖周期
}

paste 缓冲与背压

Tui::paste_buffer 是一个 Option<String>： 当某次 stdin chunk 看到 \x1b[200~ 但没等到对应的 \x1b[201~，就开始攒；下一个 chunk 接上后才合成一个 InputEvent::Paste。这避免了"大段粘贴被切成几百个 Key 事件" 把 Editor 的 undo 栈撑爆的情况。

overlay & cursor

Overlay 合成与硬件光标定位

组件树是"扁平 + 顺序"的，但实际产品里你经常需要弹一个 Dialog、Toast、 自动补全列表——这些就是 Overlay。hand-tui 把 Overlay 实现成"在最终 Vec<String> 上做行级覆盖"， 而不是给组件树插一层 z-index。

CURSOR_MARKER：用 APC 序列藏硬件光标位置

pub const CURSOR_MARKER: &str = "\x1b_hand:c\x07";
//                                 ^^^^^^^^^^^^^^^^^
//                                 APC: ESC _  payload  BEL
// 终端把 APC 当 0 宽度无副作用，所以即便意外漏出去也不留痕

焦点组件把这个 marker 嵌进自己 render 出的行里。Tui 每帧扫描 extract_cursor_position：

1. 从下往上找位于 viewport 内的最后一个 marker，记下 (row, col)
2. 把所有 marker 字节从所有行里剥掉，避免泄到终端
3. 渲染完后用 \x1b[{n}A\x1b[{col}G 把硬件光标挪到那个位置
4. 下一次 diff 前再把光标"还回"区域底部，维持 DiffRenderer 的不变量

整套设计的精彩之处在于：组件根本不需要知道自己在第几行， 只要在自己的 render 里"在该闪光标的地方插这串字节"就行。

built-in components

16 个内建组件

覆盖从最朴素的 Text 到带 undo/redo 的 Editor， 再到 Kitty/iTerm2 图像协议的 Image。 所有组件都 纯 Rust、零外部 binary 依赖。

复杂度集中在三个组件

theme

主题系统：四种颜色表示，一个 Style 链式 API

Color 枚举支持 Named / Index(u8) / Rgb / Hex， 每种自动展开为对应的 ANSI 前景 / 背景序列。 Style 是 builder 风格，.apply(text) 输出 \x1b[…]m TEXT \x1b[0m，自带 reset 收尾。

use hand_tui::theme::{Theme, Style, Color, NamedColor};

let dark  = Theme::dark();
let light = Theme::light();

let styled = Style::new()
    .fg(Color::Named(NamedColor::Green))
    .bold()
    .apply("styled text");

// 任何一种颜色表示都行
let c1 = Color::Hex("#ff6600".to_string());
let c2 = Color::Rgb { r: 255, g: 122, b: 69 };
let c3 = Color::Index(208);

Color 实现了 Serialize/Deserialize， 所以主题可以直接写进 JSON 配置——这对"让用户在配置文件里自定义颜色" 的场景非常关键。

known limits

已知边界与权衡

这是 hand-tui 0.1，README 把"和上游 TS 实现不一致的地方" 整齐地列了出来。这种主动揭短的姿态值得抄。

quickstart

最小可运行示例

use hand_tui::{Container, Component, TextComponent};

fn main() {
    let mut root = Container::new();
    root.add_child(Box::new(
        TextComponent::new("Hello from hand-tui"),
    ));

    let lines = root.render(80);
    for line in lines {
        println!("{line}");
    }
}

use hand_tui::{Tui, ProcessTerminal, EditorComponent};

#[tokio::main]
async fn main() -> hand_tui::TuiResult<()> {
    let term = ProcessTerminal::new()?;
    let mut tui  = Tui::new(Box::new(term));

    let editor_id = tui.root_mut()
        .add_child_with_id(Box::new(
            EditorComponent::new(),
        ));
    tui.set_focus(Some(editor_id));

    tui.run().await
}

takeaways

读完这套代码可以带走什么

1. 把"光标位置不变量"当成约束级语言写进 doc comment。 这种把"模块内的隐性契约"写在源文件最顶头的姿态，让任何后人改这段代码 都明白"哪一条不能动"。
2. 用 marker 字节传通信。 APC（ESC _ ... BEL）是个被遗忘的角落——零宽、终端忽略， 天然适合做"组件 → 框架"的元数据通道。CURSOR_MARKER 是个干净的范例。
3. 把同步重组和异步分发切干净。 StdinBuffer 一行 async 都没有，所有失败模式都能用 Vec<u8> 的单测覆盖；异步只活在最外层的 Tui::run。
4. 纯函数 render 是组件级测试的前提。 "宽度 → 行数组"的签名让所有组件 test 都长一个样： assert_eq!(c.render(80), vec![...])。
5. 主动列举边界比假装没有更有说服力。 README 把和上游不一致的 6 个点全摆出来——这反而让人敢用， 因为知道哪些坑已经标记。