@ai-agent-forge/agent-forge 0.85.0

package/docs/tui.md

@@ -0,0 +1,478 @@
+# TUI Components
+
+This page is the component reference for the built-in terminal UI. It covers the component system of [`@agent-forge/tui`](../../tui/) and its building blocks.
+
+Capability plugins cannot host custom TUI components or replace editor regions; they interact with the user through the built-in `notify`, `confirm`, `select`, and `input` prompts. Plugins can customize how their tools render by providing `renderCall`/`renderResult` on tool definitions (see [Theming](#theming)).
+
+**Source:** [`@agent-forge/tui`](../../tui/)
+
+## Component Interface
+
+All components implement:
+
+```typescript
+interface Component {
+  render(width: number): string[];
+  handleInput?(data: string): void;
+  wantsKeyRelease?: boolean;
+  invalidate(): void;
+}
+```
+
+| Method | Description |
+|--------|-------------|
+| `render(width)` | Return array of strings (one per line). Each line **must not exceed `width`**. |
+| `handleInput?(data)` | Receive keyboard input when component has focus. |
+| `wantsKeyRelease?` | If true, component receives key release events (Kitty protocol). Default: false. |
+| `invalidate()` | Clear cached render state. Called on theme changes. |
+
+The TUI appends a full SGR reset and OSC 8 reset at the end of each rendered line. Styles do not carry across lines. If you emit multi-line text with styling, reapply styles per line or use `wrapTextWithAnsi()` so styles are preserved for each wrapped line.
+
+## Focusable Interface (IME Support)
+
+Components that display a text cursor and need IME (Input Method Editor) support should implement the `Focusable` interface:
+
+```typescript
+import { CURSOR_MARKER, type Component, type Focusable } from "@agent-forge/tui";
+
+class MyInput implements Component, Focusable {
+  focused: boolean = false;  // Set by TUI when focus changes
+  
+  render(width: number): string[] {
+    const marker = this.focused ? CURSOR_MARKER : "";
+    // Emit marker right before the fake cursor
+    return [`> ${beforeCursor}${marker}\x1b[7m${atCursor}\x1b[27m${afterCursor}`];
+  }
+}
+```
+
+When a `Focusable` component has focus, TUI:
+1. Sets `focused = true` on the component
+2. Scans rendered output for `CURSOR_MARKER` (a zero-width APC escape sequence)
+3. Positions the hardware terminal cursor at that location
+4. Shows the hardware cursor only when `showHardwareCursor` is enabled
+
+The cursor remains hidden by default. This keeps the fake cursor rendering, while still positioning the hardware cursor for terminals that track IME candidate windows with hidden cursors. Some terminals require a visible hardware cursor for IME positioning; enable it with `showHardwareCursor`, `setShowHardwareCursor(true)`, or `PI_HARDWARE_CURSOR=1`. The `Editor` and `Input` built-in components already implement this interface.
+
+### Container Components with Embedded Inputs
+
+When a container component (dialog, selector, etc.) contains an `Input` or `Editor` child, the container must implement `Focusable` and propagate the focus state to the child. Otherwise, the hardware cursor won't be positioned correctly for IME input.
+
+```typescript
+import { Container, type Focusable, Input } from "@agent-forge/tui";
+
+class SearchDialog extends Container implements Focusable {
+  private searchInput: Input;
+
+  // Focusable implementation - propagate to child input for IME cursor positioning
+  private _focused = false;
+  get focused(): boolean {
+    return this._focused;
+  }
+  set focused(value: boolean) {
+    this._focused = value;
+    this.searchInput.focused = value;
+  }
+
+  constructor() {
+    super();
+    this.searchInput = new Input();
+    this.addChild(this.searchInput);
+  }
+}
+```
+
+Without this propagation, typing with an IME (Chinese, Japanese, Korean, etc.) will show the candidate window in the wrong position on screen.
+
+## Built-in Components
+
+Import from `@agent-forge/tui`:
+
+```typescript
+import { Text, Box, Container, Spacer, Markdown } from "@agent-forge/tui";
+```
+
+### Text
+
+Multi-line text with word wrapping.
+
+```typescript
+const text = new Text(
+  "Hello World",    // content
+  1,                // paddingX (default: 1)
+  1,                // paddingY (default: 1)
+  (s) => bgGray(s)  // optional background function
+);
+text.setText("Updated");
+```
+
+### Box
+
+Container with padding and background color.
+
+```typescript
+const box = new Box(
+  1,                // paddingX
+  1,                // paddingY
+  (s) => bgGray(s)  // background function
+);
+box.addChild(new Text("Content", 0, 0));
+box.setBgFn((s) => bgBlue(s));
+```
+
+### Container
+
+Groups child components vertically.
+
+```typescript
+const container = new Container();
+container.addChild(component1);
+container.addChild(component2);
+container.removeChild(component1);
+```
+
+### Spacer
+
+Empty vertical space.
+
+```typescript
+const spacer = new Spacer(2);  // 2 empty lines
+```
+
+### Markdown
+
+Renders markdown with syntax highlighting.
+
+```typescript
+const md = new Markdown(
+  "# Title\n\nSome **bold** text",
+  1,        // paddingX
+  1,        // paddingY
+  theme     // MarkdownTheme (see below)
+);
+md.setText("Updated markdown");
+```
+
+### Image
+
+Renders images in supported terminals (Kitty, iTerm2, Ghostty, WezTerm, Warp).
+
+```typescript
+const image = new Image(
+  base64Data,   // base64-encoded image
+  "image/png",  // MIME type
+  theme,        // ImageTheme
+  { maxWidthCells: 80, maxHeightCells: 24 }
+);
+```
+
+## Keyboard Input
+
+Use `matchesKey()` for key detection:
+
+```typescript
+import { matchesKey, Key } from "@agent-forge/tui";
+
+handleInput(data: string) {
+  if (matchesKey(data, Key.up)) {
+    this.selectedIndex--;
+  } else if (matchesKey(data, Key.enter)) {
+    this.onSelect?.(this.selectedIndex);
+  } else if (matchesKey(data, Key.escape)) {
+    this.onCancel?.();
+  } else if (matchesKey(data, Key.ctrl("c"))) {
+    // Ctrl+C
+  }
+}
+```
+
+**Key identifiers** (use `Key.*` for autocomplete, or string literals):
+- Basic keys: `Key.enter`, `Key.escape`, `Key.tab`, `Key.space`, `Key.backspace`, `Key.delete`, `Key.home`, `Key.end`
+- Arrow keys: `Key.up`, `Key.down`, `Key.left`, `Key.right`
+- With modifiers: `Key.ctrl("c")`, `Key.shift("tab")`, `Key.alt("left")`, `Key.ctrlShift("p")`
+- String format also works: `"enter"`, `"ctrl+c"`, `"shift+tab"`, `"ctrl+shift+p"`
+
+## Line Width
+
+**Critical:** Each line from `render()` must not exceed the `width` parameter.
+
+```typescript
+import { visibleWidth, truncateToWidth } from "@agent-forge/tui";
+
+render(width: number): string[] {
+  // Truncate long lines
+  return [truncateToWidth(this.text, width)];
+}
+```
+
+Utilities:
+- `visibleWidth(str)` - Get display width (ignores ANSI codes)
+- `truncateToWidth(str, width, ellipsis?)` - Truncate with optional ellipsis
+- `wrapTextWithAnsi(str, width)` - Word wrap preserving ANSI codes
+
+## Creating Custom Components
+
+Example: Interactive selector
+
+```typescript
+import {
+  matchesKey, Key,
+  truncateToWidth, visibleWidth
+} from "@agent-forge/tui";
+
+class MySelector {
+  private items: string[];
+  private selected = 0;
+  private cachedWidth?: number;
+  private cachedLines?: string[];
+  
+  public onSelect?: (item: string) => void;
+  public onCancel?: () => void;
+
+  constructor(items: string[]) {
+    this.items = items;
+  }
+
+  handleInput(data: string): void {
+    if (matchesKey(data, Key.up) && this.selected > 0) {
+      this.selected--;
+      this.invalidate();
+    } else if (matchesKey(data, Key.down) && this.selected < this.items.length - 1) {
+      this.selected++;
+      this.invalidate();
+    } else if (matchesKey(data, Key.enter)) {
+      this.onSelect?.(this.items[this.selected]);
+    } else if (matchesKey(data, Key.escape)) {
+      this.onCancel?.();
+    }
+  }
+
+  render(width: number): string[] {
+    if (this.cachedLines && this.cachedWidth === width) {
+      return this.cachedLines;
+    }
+
+    this.cachedLines = this.items.map((item, i) => {
+      const prefix = i === this.selected ? "> " : "  ";
+      return truncateToWidth(prefix + item, width);
+    });
+    this.cachedWidth = width;
+    return this.cachedLines;
+  }
+
+  invalidate(): void {
+    this.cachedWidth = undefined;
+    this.cachedLines = undefined;
+  }
+}
+```
+
+## Theming
+
+Components accept theme objects for styling.
+
+**In `renderCall`/`renderResult`**, use the `theme` parameter:
+
+```typescript
+renderResult(result, options, theme, context) {
+  // Use theme.fg() for foreground colors
+  return new Text(theme.fg("success", "Done!"), 0, 0);
+  
+  // Use theme.bg() for background colors
+  const styled = theme.bg("toolPendingBg", theme.fg("accent", "text"));
+}
+```
+
+**Foreground colors** (`theme.fg(color, text)`):
+
+| Category | Colors |
+|----------|--------|
+| General | `text`, `accent`, `muted`, `dim`, `searchMatchText` |
+| Status | `success`, `error`, `warning` |
+| Borders | `border`, `borderAccent`, `borderMuted` |
+| Messages | `userMessageText`, `customMessageText`, `customMessageLabel` |
+| Tools | `toolTitle`, `toolOutput` |
+| Diffs | `toolDiffAdded`, `toolDiffRemoved`, `toolDiffContext` |
+| Markdown | `mdHeading`, `mdLink`, `mdLinkUrl`, `mdCode`, `mdCodeBlock`, `mdCodeBlockBorder`, `mdQuote`, `mdQuoteBorder`, `mdHr`, `mdListBullet` |
+| Syntax | `syntaxComment`, `syntaxKeyword`, `syntaxFunction`, `syntaxVariable`, `syntaxString`, `syntaxNumber`, `syntaxType`, `syntaxOperator`, `syntaxPunctuation` |
+| Thinking | `thinkingOff`, `thinkingMinimal`, `thinkingLow`, `thinkingMedium`, `thinkingHigh`, `thinkingXhigh`, `thinkingMax` |
+| Modes | `bashMode` |
+
+**Background colors** (`theme.bg(color, text)`):
+
+`selectedBg`, `searchMatchBg`, `userMessageBg`, `customMessageBg`, `toolPendingBg`, `toolSuccessBg`, `toolErrorBg`
+
+**For Markdown**, use `getMarkdownTheme()`:
+
+```typescript
+import { getMarkdownTheme } from "@agent-forge/agent-forge";
+import { Markdown } from "@agent-forge/tui";
+
+renderResult(result, options, theme, context) {
+  const mdTheme = getMarkdownTheme();
+  return new Markdown(result.details.markdown, 0, 0, mdTheme);
+}
+```
+
+**For custom components**, define your own theme interface:
+
+```typescript
+interface MyTheme {
+  selected: (s: string) => string;
+  normal: (s: string) => string;
+}
+```
+
+## Debug logging
+
+Set `AGENT_FORGE_TUI_WRITE_LOG` to capture the raw ANSI stream written to stdout.
+
+```bash
+AGENT_FORGE_TUI_WRITE_LOG=/tmp/tui-ansi.log npx tsx packages/tui/test/chat-simple.ts
+```
+
+## Performance
+
+Cache rendered output when possible:
+
+```typescript
+class CachedComponent {
+  private cachedWidth?: number;
+  private cachedLines?: string[];
+
+  render(width: number): string[] {
+    if (this.cachedLines && this.cachedWidth === width) {
+      return this.cachedLines;
+    }
+    // ... compute lines ...
+    this.cachedWidth = width;
+    this.cachedLines = lines;
+    return lines;
+  }
+
+  invalidate(): void {
+    this.cachedWidth = undefined;
+    this.cachedLines = undefined;
+  }
+}
+```
+
+Call `invalidate()` when state changes, then use the injected `tui.requestRender()` to trigger re-render.
+
+## Invalidation and Theme Changes
+
+When the theme changes, the TUI calls `invalidate()` on all components to clear their caches. Components must properly implement `invalidate()` to ensure theme changes take effect.
+
+### The Problem
+
+If a component pre-bakes theme colors into strings (via `theme.fg()`, `theme.bg()`, etc.) and caches them, the cached strings contain ANSI escape codes from the old theme. Simply clearing the render cache isn't enough if the component stores the themed content separately.
+
+**Wrong approach** (theme colors won't update):
+
+```typescript
+class BadComponent extends Container {
+  private content: Text;
+
+  constructor(message: string, theme: Theme) {
+    super();
+    // Pre-baked theme colors stored in Text component
+    this.content = new Text(theme.fg("accent", message), 1, 0);
+    this.addChild(this.content);
+  }
+  // No invalidate override - parent's invalidate only clears
+  // child render caches, not the pre-baked content
+}
+```
+
+### The Solution
+
+Components that build content with theme colors must rebuild that content when `invalidate()` is called:
+
+```typescript
+class GoodComponent extends Container {
+  private message: string;
+  private content: Text;
+
+  constructor(message: string) {
+    super();
+    this.message = message;
+    this.content = new Text("", 1, 0);
+    this.addChild(this.content);
+    this.updateDisplay();
+  }
+
+  private updateDisplay(): void {
+    // Rebuild content with current theme
+    this.content.setText(theme.fg("accent", this.message));
+  }
+
+  override invalidate(): void {
+    super.invalidate();  // Clear child caches
+    this.updateDisplay(); // Rebuild with new theme
+  }
+}
+```
+
+### Pattern: Rebuild on Invalidate
+
+For components with complex content:
+
+```typescript
+class ComplexComponent extends Container {
+  private data: SomeData;
+
+  constructor(data: SomeData) {
+    super();
+    this.data = data;
+    this.rebuild();
+  }
+
+  private rebuild(): void {
+    this.clear();  // Remove all children
+
+    // Build UI with current theme
+    this.addChild(new Text(theme.fg("accent", theme.bold("Title")), 1, 0));
+    this.addChild(new Spacer(1));
+
+    for (const item of this.data.items) {
+      const color = item.active ? "success" : "muted";
+      this.addChild(new Text(theme.fg(color, item.label), 1, 0));
+    }
+  }
+
+  override invalidate(): void {
+    super.invalidate();
+    this.rebuild();
+  }
+}
+```
+
+### When This Matters
+
+This pattern is needed when:
+
+1. **Pre-baking theme colors** - Using `theme.fg()` or `theme.bg()` to create styled strings stored in child components
+2. **Syntax highlighting** - Using `highlightCode()` which applies theme-based syntax colors
+3. **Complex layouts** - Building child component trees that embed theme colors
+
+This pattern is NOT needed when:
+
+1. **Using theme callbacks** - Passing functions like `(text) => theme.fg("accent", text)` that are called during render
+2. **Simple containers** - Just grouping other components without adding themed content
+3. **Stateless render** - Computing themed output fresh in every `render()` call (no caching)
+
+## Key Rules
+
+1. **Always use the theme passed to your component** - Don't import theme directly. Renderers and component factories receive the current `theme` as a parameter.
+
+2. **Always type DynamicBorder color param** - Write `(s: string) => theme.fg("accent", s)`, not `(s) => theme.fg("accent", s)`.
+
+3. **Call tui.requestRender() after state changes** - In `handleInput`, call `tui.requestRender()` after updating state.
+
+4. **Return the three-method object** - Custom components need `{ render, invalidate, handleInput }`.
+
+5. **Use existing components** - `SelectList`, `SettingsList`, `BorderedLoader` cover 90% of cases. Don't rebuild them.
+
+## Examples
+
+The extension UI examples that used to accompany this page (selection UI, async cancel, settings toggles, status indicators, working indicator, custom footer, custom editor) were removed together with the legacy ExtensionAPI (D-064). For capability plugin examples, see [`examples/extensions/`](../examples/extensions/); for a renderer-focused example, see [`examples/extensions/built-in-tool-renderer/`](../examples/extensions/built-in-tool-renderer/).