tui@earendil-works/pi-tui

要点Key points

• 最大的文件是 components/editor.ts：多行编辑、撤销、kill ring、历史、粘贴折叠与补全菜单都在这里。The largest file is components/editor.ts: multi-line editing, undo, the kill ring, history, paste folding and the completion menu all live there.
• utils.ts 的 visibleWidth() / truncateToWidth() 处理 ANSI 序列与全角字符，是所有组件遵守宽度约定的基础。utils.ts's visibleWidth() / truncateToWidth() handle ANSI sequences and wide characters; every component relies on them to respect the width contract.
• native-platform.ts 加载可选的原生模块（剪贴板、修饰键状态）；没有时功能降级而不报错。native-platform.ts loads an optional native module (clipboard, modifier state); without it features degrade instead of failing.

工作原理How it works

1. 创建 ProcessTerminal，再用它创建 TuiMainScreen 或 TuiAltScreen。Create a ProcessTerminal, then a TuiMainScreen or TuiAltScreen on top of it.
2. addChild() 组件、setFocus() 输入组件，start()。addChild() components, setFocus() the input component, start().
3. 状态变化后调用 requestRender()；输入由 TUI 交给获得焦点的组件。Call requestRender() after state changes; the TUI routes input to the focused component.

要点Key points

• 每一行的可见宽度不能超过 width；超过时 TUI 抛错并写 pi-tui-crash.log，而不是让终端自动换行弄乱画面。No line may be wider than width; if one is, the TUI throws and writes pi-tui-crash.log instead of letting the terminal wrap and corrupt the screen.
• 获得焦点的组件（Focusable.focused = true）在光标处输出零宽的 CURSOR_MARKER；TUI 找到它、删掉它，再把硬件光标移过去——输入法候选框因此出现在正确位置。The focused component (Focusable.focused = true) emits a zero-width CURSOR_MARKER at the cursor; the TUI finds it, strips it and moves the hardware cursor there — so IME candidate windows appear in the right place.
• 每行末尾都追加 SEGMENT_RESET（重置样式并关闭超链接），一行的样式不会漏到下一行。SEGMENT_RESET (reset style, close hyperlinks) is appended to every line, so styles never leak into the next line.
• wantsKeyRelease 默认 false：Kitty 协议的按键释放事件会被过滤，组件需要时再显式打开。wantsKeyRelease defaults to false: Kitty key-release events are filtered unless a component opts in.

工作原理How it works

1. 实现 render(width)：用 visibleWidth() / truncateToWidth() 保证每行不超宽。Implement render(width): use visibleWidth() / truncateToWidth() so no line is too wide.
2. 需要输入就实现 handleInput(data)，用 matchesKey(data, "ctrl+c") 等判断按键。For input, implement handleInput(data) and test keys with matchesKey(data, "ctrl+c") and friends.
3. 缓存渲染结果时实现 invalidate()，主题变化时 TUI 会调用它。If you cache rendered output, implement invalidate(); the TUI calls it when the theme changes.

要点Key points

• Container 组合子组件；可选的 handleInput / handleMouse 处理输入。Container composes children; optional handleInput / handleMouse handle input.
• 两种屏幕：TuiMainScreen（主屏，保留 scrollback）与 TuiAltScreen（备用屏全屏）。Two screens: TuiMainScreen (main buffer, keeps scrollback) and TuiAltScreen (alternate-screen fullscreen).
• 内置组件：Editor、Input、Markdown、SelectList、Image、Loader、ScrollView、Stack 等。Built-in components: Editor, Input, Markdown, SelectList, Image, Loader, ScrollView, Stack and more.

工作原理How it works

1. ProcessTerminal 用 StdinBuffer 把批量到达的输入拆成完整的按键序列，交给获得焦点的组件。ProcessTerminal uses StdinBuffer to split batched input into complete key sequences for the focused component.
2. requestRender() 在 process.nextTick 中合并请求，scheduleRender() 保证两帧间隔 ≥ MIN_RENDER_INTERVAL_MS（16 ms）；force 会立即渲染。requestRender() coalesces on process.nextTick; scheduleRender() keeps frames ≥ MIN_RENDER_INTERVAL_MS (16 ms) apart; force renders immediately.
3. TuiMainScreen.doRender() 合成 overlay 后与 previousLines 比较，在同步输出（CSI ?2026h）中只写出变化的行。TuiMainScreen.doRender() composites overlays, diffs against previousLines, and writes only changed lines inside synchronized output (CSI ?2026h).

要点Key points

• 宽度变化、高度变化（Termux 除外）、内容变短（开启 clearOnShrink 时）以及变化发生在视口上方时，会清屏重绘——终端滚动区里已经滚出去的行无法原地修改。A width change, a height change (except on Termux), shrinking content (with clearOnShrink) or a change above the viewport triggers a full redraw — lines already scrolled into the terminal's history cannot be edited in place.
• 只删了行时不重写任何内容，只清掉尾部多出来的行。If lines were only deleted, nothing is rewritten; the extra tail lines are just cleared.
• Kitty 图片占多行：变化区间会扩大到覆盖整张图，避免半张图残留。Kitty images span several rows: the changed range widens to cover the whole image so no half-image remains.
• TUI.fullRedraws 记录全量重绘次数，可用来检查组件是否引起了不必要的重绘。TUI.fullRedraws counts full redraws, handy for spotting components that cause needless redraws.

工作原理How it works

1. 准备一帧：render(width) → compositeOverlays() → extractCursorPosition() → applyLineResets()。Prepare a frame: render(width) → compositeOverlays() → extractCursorPosition() → applyLineResets().
2. 依次判断是否需要全量重绘（见图中 7 个判断）。Check, in order, whether a full redraw is needed (the seven checks in the figure).
3. 否则移动光标到 firstChanged，逐行写到 lastChanged，每行先 \x1b[2K 清除。Otherwise move to firstChanged and write each line through lastChanged, clearing each with \x1b[2K first.
4. 最后把硬件光标放到 CURSOR_MARKER 的位置。Finally place the hardware cursor where CURSOR_MARKER was.

要点Key points

• 备用屏一帧依次经过：布局帧 → 搜索高亮 → 回到底部提示 → 覆盖层 → 选区 → 短暂提示 → 光标与行尾重置，最后只写变化的行。An alternate-screen frame goes through: layout frame → search highlights → jump-to-end pill → overlays → selection → flashes → cursor and line resets, then only changed rows are written.
• 备用屏开启鼠标报告（?1000/?1002/?1003/?1004/?1006），滚轮带加速，选择后可通过 OSC 52 复制。The alternate screen enables mouse reporting (?1000/?1002/?1003/?1004/?1006), accelerated wheel scrolling, and copy via OSC 52 after a selection.
• 布局用 HStack / VStack / ScrollView，支持 basis / grow / shrink；regular 屏幕不需要这些。Layout uses HStack / VStack / ScrollView with basis / grow / shrink; the regular screen does without.

工作原理How it works

1. TuiAltScreen.start() 写 \x1b[?1049h 进入备用屏并开启鼠标。TuiAltScreen.start() writes \x1b[?1049h to enter the alternate screen and enables the mouse.
2. doRender() 调 renderLayoutFrame(root, width, height) 得到布局与行。doRender() calls renderLayoutFrame(root, width, height) for the layout and lines.
3. 与 previousScreen 逐行比较；尺寸变化时整屏重绘。Compare row by row with previousScreen; redraw the whole screen when the size changes.

要点Key points

• 单独的 ESC 要等 10ms 才能确定是 Escape 键而不是序列开头；SSH 下默认 100ms，可用 PI_TUI_ESC_TIMEOUT 调整。A lone ESC needs 10 ms to be sure it is the Escape key rather than the start of a sequence; 100 ms over SSH, adjustable with PI_TUI_ESC_TIMEOUT.
• 启动时请求 Kitty 键盘协议（flags 7）；终端不回复时改用 modifyOtherKeys，这样 shift+enter 等组合键仍可区分。Start-up requests the Kitty keyboard protocol (flags 7); if the terminal stays silent it falls back to modifyOtherKeys so combos like shift+enter remain distinguishable.
• 按键用语义 id 表示（tui.input.submit、tui.editor.undo …，共 47 个），默认键位可被用户覆盖。Keys are referred to by semantic ids (tui.input.submit, tui.editor.undo …, 47 in total), and users can override the default bindings.

工作原理How it works

1. ProcessTerminal.start() 打开 raw 模式与括号粘贴，并发送协议查询。ProcessTerminal.start() enables raw mode and bracketed paste and sends the protocol queries.
2. StdinBuffer 输出完整序列；括号粘贴内容作为一整段交付。StdinBuffer emits whole sequences; bracketed-paste content is delivered as one chunk.
3. handleTerminalInput(data) 走完 8 步，调用 focused.handleInput(data)，再立即渲染。handleTerminalInput(data) runs the eight steps, calls focused.handleInput(data), then renders immediately.
4. 组件里用 getKeybindings().matches(data, id) 或 matchesKey(data, "ctrl+c") 判断。Inside components, test with getKeybindings().matches(data, id) or matchesKey(data, "ctrl+c").

要点Key points

• 超过 10 行或 1000 字符的粘贴显示为 [paste #1 +42 lines] 这样的标记，提交时再换回原文——编辑器本身保持轻量。Pastes over 10 lines or 1000 characters show as markers like [paste #1 +42 lines] and expand back on submit — the editor itself stays light.
• 内置的 CombinedAutocompleteProvider 处理三种情况：行首 / 的斜杠命令（模糊匹配）、@ 文件附件（用 fd 搜索，20ms 防抖）、Tab 路径补全。The built-in CombinedAutocompleteProvider covers three cases: / slash commands at line start (fuzzy matched), @ file attachments (searched with fd, 20 ms debounce), and Tab path completion.
• 光标前一个字符是 \ 时，Enter 会删掉它并插入换行而不是提交——给不支持 shift+enter 的终端用。When the character before the cursor is \, Enter deletes it and inserts a newline instead of submitting — a workaround for terminals without shift+enter.

工作原理How it works

1. handleInput(data)：跳转模式 → 括号粘贴 → ctrl+c 交给上层 → 撤销 → 补全菜单 → … → 提交 → 插入字符。handleInput(data): jump mode → bracketed paste → ctrl+c to the parent → undo → completion menu → … → submit → insert text.
2. 输入触发字符后调用 provider.getSuggestions(lines, line, col, { signal })，结果显示在 SelectList 中。After a trigger character, provider.getSuggestions(lines, line, col, { signal }) runs and results show in a SelectList.
3. 确认后 applyCompletion() 返回新的文本与光标位置。On confirm, applyCompletion() returns the new text and cursor position.

要点Key points

• 默认居中，宽度为 min(80, 可用宽度)；width / maxHeight / row / col 都接受数字或 "50%" 这样的百分比。Default: centred, width min(80, available); width / maxHeight / row / col accept a number or a percentage such as "50%".
• visible(w, h) 每帧重新求值：终端变小时覆盖层可以自动隐藏，焦点也随之转移。visible(w, h) is re-evaluated every frame: an overlay can hide itself on small terminals, and focus moves accordingly.
• nonCapturing: true 的覆盖层只显示、不抢焦点，适合状态提示。A nonCapturing: true overlay shows without taking focus — good for status pop-ups.

工作原理How it works

1. showOverlay() 记下当前焦点为 preFocus，把覆盖层压栈并聚焦（nonCapturing 除外）。showOverlay() records the current focus as preFocus, pushes the overlay and focuses it (unless nonCapturing).
2. 每帧：筛选可见的 → 解析宽度 → render(width) 并截到 maxHeight → 用实际高度解析 row/col → compositeLineAt()。Each frame: filter visible → resolve width → render(width) cut to maxHeight → resolve row/col with the real height → compositeLineAt().
3. hide() 出栈，焦点交给下一个可见覆盖层或 preFocus。hide() pops it; focus goes to the next visible overlay or preFocus.

要点Key points

• 图片：kitty、ghostty、wezterm、warp 用 Kitty 图形协议，iTerm2 用自己的协议；tmux、screen 与其他终端不显示图片。Images: kitty, ghostty, wezterm and warp use the Kitty graphics protocol, iTerm2 its own; tmux, screen and other terminals show no images.
• 超链接（OSC 8）只在确认支持的终端里开启，否则 URL 会被吞掉；tmux 下会实际探测是否转发。Hyperlinks (OSC 8) are enabled only where known to work, since otherwise the URL disappears; under tmux forwarding is actually probed.
• DA 查询（\x1b[c）用作“查询结束”的哨兵：在它之前没收到 Kitty 回复，就说明终端不支持。The DA query (\x1b[c) is the end-of-queries sentinel: no Kitty reply before it means no support.

工作原理How it works

1. start(onInput, onResize)：raw 模式 → ?2004h → Kitty 查询 → DA。start(onInput, onResize): raw mode → ?2004h → Kitty query → DA.
2. detectCapabilities() 根据 TERM_PROGRAM、KITTY_WINDOW_ID、TMUX 等变量给出 images / trueColor / hyperlinks。detectCapabilities() derives images / trueColor / hyperlinks from TERM_PROGRAM, KITTY_WINDOW_ID, TMUX and similar variables.
3. stop() 关闭各模式并恢复原来的 raw 状态。stop() turns the modes off and restores the previous raw state.