omegon 0.6.0

package/skills/pi-extensions/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: pi-extensions
+description: Pi extension API reference and conventions. Use when creating, modifying, or debugging pi extensions — covers registerCommand, registerTool, event handlers, UI context, and common pitfalls.
+---
+
+# Pi Extension API — Quick Reference
+
+Extensions are TypeScript modules exporting a default function that receives `ExtensionAPI`.
+
+```typescript
+import type { ExtensionAPI } from "@cwilson613/pi-coding-agent";
+
+export default function (pi: ExtensionAPI) {
+  // register tools, commands, shortcuts, event handlers
+}
+```
+
+The factory can be `async` if initialization requires it.
+
+## Commands
+
+**Method:** `pi.registerCommand(name, options)`
+
+```typescript
+pi.registerCommand("my-command", {
+  description: "What this command does",
+  handler: async (args: string, ctx: ExtensionCommandContext) => {
+    // args is the raw string after the command name
+    // ctx provides ui, sessionManager, model, etc.
+    ctx.ui.notify("Hello", "info");
+  },
+});
+```
+
+**⚠️ Common mistakes:**
+- There is NO `addCommand` method. Only `registerCommand` exists.
+- The handler signature is `handler(args, ctx)` — args first, context second.
+- There is NO `ctx.say()` method. Use `ctx.ui.notify(message, type)`.
+- There is NO `execute` property. The callback property is `handler`.
+
+### UI Methods on `ctx.ui`
+
+| Method | Signature | Notes |
+|--------|-----------|-------|
+| `notify` | `(message: string, type?: "info" \| "warning" \| "error") => void` | Non-blocking notification |
+| `confirm` | `(title: string, message: string, opts?) => Promise<boolean>` | **Two** string args required |
+| `select` | `(title: string, options: string[], opts?) => Promise<string \| undefined>` | Returns selected item |
+| `input` | `(title: string, placeholder?: string, opts?) => Promise<string \| undefined>` | Text input dialog |
+| `setStatus` | `(key: string, text: string \| undefined) => void` | Footer status line |
+| `setWidget` | `(key: string, content, options?) => void` | Widget above/below editor |
+| `setFooter` | `(factory \| undefined) => void` | Custom footer component |
+
+**⚠️ `confirm()` takes TWO string arguments** (title + message), not one. A single-arg call is a type error.
+
+## Tools
+
+**Method:** `pi.registerTool(toolDefinition)`
+
+```typescript
+import { Type } from "@sinclair/typebox";
+
+pi.registerTool({
+  name: "my_tool",
+  label: "My Tool",
+  description: "What this tool does (shown to LLM)",
+  promptSnippet: "One-liner for Available Tools section",
+  promptGuidelines: ["Bullet points appended to system prompt Guidelines"],
+  parameters: Type.Object({
+    action: Type.String({ description: "What to do" }),
+    target: Type.Optional(Type.String({ description: "Optional target" })),
+  }),
+  execute: async (toolCallId, params, signal, onUpdate, ctx) => {
+    // params is typed from the schema
+    // signal: AbortSignal | undefined
+    // onUpdate: streaming partial results callback
+    // ctx: ExtensionContext (NOT ExtensionCommandContext)
+    return {
+      content: [{ type: "text", text: "result" }],
+    };
+  },
+});
+```
+
+**Key differences from commands:**
+- Tools are called by the LLM, commands by the user via `/` prefix.
+- Tool `execute` receives `(toolCallId, params, signal, onUpdate, ctx)`.
+- Tool `ctx` is `ExtensionContext` (no `waitForIdle`, `newSession`, etc.).
+- Tool results must return `{ content: Array<{type: "text", text: string}> }`.
+
+### StringEnum helper
+
+For enum parameters, use the local helper (NOT `@cwilson613/pi-ai`):
+
+```typescript
+import { StringEnum } from "../lib/typebox-helpers";
+
+// In parameters:
+action: StringEnum(["start", "stop", "status"], { description: "Action" }),
+```
+
+## Event Handlers
+
+**Method:** `pi.on(eventName, handler)`
+
+```typescript
+pi.on("session_start", async (event, ctx) => { ... });
+pi.on("session_shutdown", async (event, ctx) => { ... });
+```
+
+### Valid Event Names
+
+| Event | When | Can return |
+|-------|------|------------|
+| `session_start` | Session loaded | void |
+| `session_shutdown` | Process exiting | void |
+| `session_before_compact` | Before compaction | `{ cancel?, compaction? }` |
+| `session_compact` | After compaction | void |
+| `session_before_switch` | Before session switch | `{ cancel? }` |
+| `session_switch` | After session switch | void |
+| `session_before_fork` | Before fork | `{ cancel? }` |
+| `session_fork` | After fork | void |
+| `session_before_tree` | Before tree nav | `{ cancel?, summary? }` |
+| `session_tree` | After tree nav | void |
+| `context` | Before LLM call | `{ messages? }` |
+| `before_agent_start` | After user input | `{ message?, systemPrompt? }` |
+| `agent_start` | Agent loop begins | void |
+| `agent_end` | Agent loop ends | void |
+| `turn_start` / `turn_end` | Each turn | void |
+| `message_start` / `message_update` / `message_end` | Message lifecycle | void |
+| `tool_execution_start` / `tool_execution_update` / `tool_execution_end` | Tool lifecycle | void |
+| `model_select` | Model changed | void |
+| `tool_call` | Before tool executes | `{ block?, reason? }` |
+| `tool_result` | After tool executes | `{ content?, isError? }` |
+| `input` | User input received | `{ action: "continue" \| "transform" \| "handled" }` |
+| `resources_discover` | After session_start | `{ skillPaths?, promptPaths?, themePaths? }` |
+
+**⚠️ There is NO `session_end` event.** The cleanup event is `session_shutdown`.
+
+## Cross-Extension Communication
+
+Use the shared event bus for decoupled extension-to-extension messaging:
+
+```typescript
+// Emitter
+pi.events.emit("my-event", data);
+
+// Listener
+pi.events.on("my-event", (data) => { ... });
+```
+
+For shared state, use `globalThis` via `Symbol.for()`:
+
+```typescript
+const STATE_KEY = Symbol.for("pi:shared-state");
+(globalThis as any)[STATE_KEY] = sharedObject;
+```
+
+## Process Spawning in Extensions
+
+When spawning child processes from extensions:
+
+- **Use `stdio: "pipe"`** for processes whose output you capture. Never `stdio: "inherit"` — it corrupts the TUI.
+- **Use `detached: true` + `child.unref()`** for background processes that should outlive the tool call.
+- **Clean up in `session_shutdown`**: if you spawn a persistent process, kill it on shutdown.
+- **Set `NONINTERACTIVE=1`** in env for install scripts to prevent stdin prompts hanging the TUI.
+- **Respect `signal` (AbortSignal)**: register `signal.addEventListener("abort", ...)` to kill child processes on cancellation.
+
+```typescript
+// Background process with cleanup
+let child: ChildProcess | null = null;
+
+function startProcess() {
+  child = spawn("my-binary", ["serve"], { stdio: "ignore", detached: true });
+  child.unref();
+  child.on("exit", () => { child = null; });
+}
+
+pi.on("session_shutdown", () => {
+  if (child) { child.kill("SIGTERM"); child = null; }
+});
+```
+
+## Conventions
+
+- **One extension per directory** under `extensions/`. Entry point is `index.ts`.
+- **Testable domain logic** in separate files (e.g., `auth.ts`), index imports and re-exports.
+- **Types** in `types.ts` when shared across files.
+- **Config annotation** at top of file: `// @config KEY "description" [default: value]`
+- **Extension load order** defined in `package.json` → `pi.extensions` array.
+- **No circular imports** between extensions. Use shared-state or events for cross-extension data.
+- **Import `type` separately** from runtime imports: `import type { ExtensionAPI } from "..."`.

package/skills/pi-tui/SKILL.md

@@ -0,0 +1,517 @@
+---
+name: pi-tui
+description: Pi TUI component patterns and conventions for building extension UIs. Covers the Component interface, overlays, built-in components, keyboard handling, theming, footer/widget/header APIs, and common pitfalls. Use when creating or modifying TUI components in pi extensions.
+globs:
+  - extensions/**/overlay*.ts
+  - extensions/**/footer*.ts
+  - extensions/**/dashboard/**
+---
+
+# Pi TUI — Extension UI Patterns
+
+This skill covers the TUI layer for pi extensions. Read alongside `pi-extensions/SKILL.md` for the full extension API.
+
+## Package Geography
+
+```
+@cwilson613/pi-coding-agent     — ExtensionAPI, Theme, DynamicBorder, BorderedLoader, CustomEditor, etc.
+@cwilson613/pi-tui              — Component, Container, TUI, Text, Box, SelectList, etc.
+@sinclair/typebox                 — Type schema for tool parameters
+```
+
+All three are available via pi's jiti loader at runtime. **Do NOT `npm install` them** — they resolve through the alias map in the extension loader.
+
+> ⚠️ Value imports from `@cwilson613/pi-tui` (e.g. `truncateToWidth`, `matchesKey`, `visibleWidth`) work inside pi but **fail under `tsx` or `node` directly** because pi-tui is a nested dependency of pi-coding-agent. Tests that need these must either mock them or run through pi.
+
+## Component Interface
+
+Every TUI component implements:
+
+```typescript
+interface Component {
+  render(width: number): string[];   // Lines ≤ width chars each
+  handleInput?(data: string): void;  // Keyboard when focused
+  wantsKeyRelease?: boolean;         // Kitty protocol key releases
+  invalidate(): void;                // Clear cached render state
+}
+```
+
+**Critical rules:**
+1. Each line from `render()` must not exceed `width`. Use `truncateToWidth(line, width)`.
+2. Styles reset at line boundaries — reapply ANSI per line or use `wrapTextWithAnsi()`.
+3. Cache render output; invalidate on state change + call `tui.requestRender()`.
+
+## Imports Cheat Sheet
+
+```typescript
+// Types (compile-time only — safe everywhere)
+import type { ExtensionAPI, ExtensionCommandContext, Theme } from "@cwilson613/pi-coding-agent";
+import type { Component, OverlayHandle, OverlayOptions, TUI } from "@cwilson613/pi-tui";
+
+// Values from pi-coding-agent (re-exported, always available)
+import { DynamicBorder, BorderedLoader, CustomEditor } from "@cwilson613/pi-coding-agent";
+import { getMarkdownTheme, getSelectListTheme, getSettingsListTheme, highlightCode } from "@cwilson613/pi-coding-agent";
+
+// Values from pi-tui (work via jiti at runtime only)
+import { matchesKey, Key, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@cwilson613/pi-tui";
+import { Container, Text, Box, Spacer, Markdown, Image } from "@cwilson613/pi-tui";
+import { SelectList, SettingsList } from "@cwilson613/pi-tui";
+import type { SelectItem, SelectListTheme, SettingItem } from "@cwilson613/pi-tui";
+
+// TypeBox for tool parameter schemas
+import { Type } from "@sinclair/typebox";
+```
+
+## Displaying UI — The Five Surfaces
+
+### 1. `ctx.ui.custom<T>()` — Full-screen or Overlay Component
+
+The primary way to show interactive UI. Blocks until `done()` is called.
+
+```typescript
+const result = await ctx.ui.custom<string | null>(
+  (tui, theme, keybindings, done) => {
+    // Factory — return a Component (with optional dispose)
+    return new MyComponent(tui, theme, done);
+  },
+  {
+    overlay: true,                    // Render on top of chat
+    overlayOptions: { ... },          // Position/size
+    onHandle: (handle) => { ... },    // OverlayHandle for visibility control
+  }
+);
+```
+
+**Factory signature:** `(tui: TUI, theme: Theme, keybindings: KeybindingsManager, done: (result: T) => void) => Component & { dispose?(): void }`
+
+**Return type options:**
+- A class implementing `Component` + optional `dispose()`
+- An inline object: `{ render, invalidate, handleInput, dispose? }`
+
+### 2. `ctx.ui.setFooter()` — Custom Footer
+
+```typescript
+ctx.ui.setFooter((tui, theme, footerData) => ({
+  render(width: number): string[] {
+    const branch = footerData.getGitBranch();
+    const statuses = footerData.getExtensionStatuses();
+    return [truncateToWidth(`${branch} | ...`, width)];
+  },
+  invalidate() {},
+  dispose: footerData.onBranchChange(() => tui.requestRender()),
+}));
+
+ctx.ui.setFooter(undefined);  // Restore default
+```
+
+**`footerData` provides:** `getGitBranch(): string | null`, `getExtensionStatuses(): ReadonlyMap<string, string>`, `onBranchChange(cb): unsubscribe`.
+
+> ⚠️ Default footer renders 2 lines. Your replacement must handle all display.
+
+### 3. `ctx.ui.setWidget()` — Persistent Content Above/Below Editor
+
+```typescript
+// Simple string array
+ctx.ui.setWidget("my-key", ["Line 1", "Line 2"], { placement: "belowEditor" });
+
+// Component factory (has theme access)
+ctx.ui.setWidget("my-key", (tui, theme) => ({
+  render: () => [theme.fg("accent", "● Active")],
+  invalidate: () => {},
+}));
+
+ctx.ui.setWidget("my-key", undefined);  // Remove
+```
+
+### 4. `ctx.ui.setStatus()` — Footer Status Line
+
+```typescript
+ctx.ui.setStatus("my-ext", theme.fg("accent", "● running"));
+ctx.ui.setStatus("my-ext", undefined);  // Clear
+```
+
+### 5. `ctx.ui.setHeader()` — Custom Header
+
+```typescript
+ctx.ui.setHeader((tui, theme) => ({
+  render(width) { return [theme.fg("accent", "═".repeat(width))]; },
+  invalidate() {},
+}));
+ctx.ui.setHeader(undefined);  // Restore default
+```
+
+## Overlay Positioning
+
+```typescript
+overlayOptions: {
+  // Size
+  width: "40%",           // SizeValue: number | `${number}%`
+  minWidth: 40,           // Minimum columns
+  maxHeight: "80%",       // Truncates render output
+
+  // Position — anchor-based (default: "center")
+  anchor: "right-center", // 9 positions: center, top-left, top-center, top-right,
+                           //   left-center, right-center, bottom-left, bottom-center, bottom-right
+  offsetX: -2,            // Offset from anchor position
+  offsetY: 0,
+
+  // Position — absolute/percentage (alternative to anchor)
+  row: "25%",             // From top
+  col: 10,                // From left
+
+  // Margins
+  margin: 2,              // All sides, or { top, right, bottom, left }
+
+  // Responsive hiding
+  visible: (termWidth, termHeight) => termWidth >= 100,
+}
+```
+
+**OverlayHandle** (from `onHandle` callback):
+- `handle.setHidden(true/false)` — Toggle visibility
+- `handle.isHidden()` — Check state
+- `handle.hide()` — Permanently remove
+
+## Keyboard Handling
+
+```typescript
+import { matchesKey, Key } from "@cwilson613/pi-tui";
+
+handleInput(data: string): void {
+  if (matchesKey(data, Key.escape))     { /* ... */ }
+  if (matchesKey(data, Key.enter))      { /* ... */ }
+  if (matchesKey(data, Key.up))         { /* ... */ }
+  if (matchesKey(data, Key.down))       { /* ... */ }
+  if (matchesKey(data, Key.tab))        { /* ... */ }
+  if (matchesKey(data, Key.ctrl("c")))  { /* ... */ }
+  if (matchesKey(data, Key.ctrlShift("b")))  { /* ... */ }
+  // String format also works: "escape", "ctrl+c", "shift+tab"
+}
+```
+
+After handling input, call `tui.requestRender()` to trigger a redraw.
+
+## Built-in Components
+
+| Component | Import | Use for |
+|-----------|--------|---------|
+| `Container` | pi-tui | Group children vertically |
+| `Text` | pi-tui | Multi-line text with wrapping |
+| `Box` | pi-tui | Container with padding/background |
+| `Spacer` | pi-tui | Empty vertical space (`new Spacer(2)`) |
+| `Markdown` | pi-tui | Rendered markdown with syntax highlighting |
+| `Image` | pi-tui | Terminal images (Kitty/iTerm2/Ghostty/WezTerm) |
+| `SelectList` | pi-tui | Interactive item selection |
+| `SettingsList` | pi-tui | Toggle-style settings |
+| `DynamicBorder` | pi-coding-agent | Styled horizontal border |
+| `BorderedLoader` | pi-coding-agent | Spinner with cancel support |
+| `CustomEditor` | pi-coding-agent | Base class for custom editors |
+
+### SelectList
+
+```typescript
+import { SelectList } from "@cwilson613/pi-tui";
+import type { SelectItem } from "@cwilson613/pi-tui";
+
+const items: SelectItem[] = [
+  { value: "a", label: "Option A", description: "Details" },
+  { value: "b", label: "Option B" },
+];
+
+const list = new SelectList(items, visibleCount, {
+  selectedPrefix: (t) => theme.fg("accent", t),
+  selectedText: (t) => theme.fg("accent", t),
+  description: (t) => theme.fg("muted", t),
+  scrollInfo: (t) => theme.fg("dim", t),
+  noMatch: (t) => theme.fg("warning", t),
+});
+list.onSelect = (item) => done(item.value);
+list.onCancel = () => done(null);
+```
+
+## Theming
+
+**Always use the `theme` from the callback** — never import or hardcode colors.
+
+```typescript
+// Foreground
+theme.fg("accent", "text")      // Styled text
+theme.fg("muted", "text")       // Subdued
+theme.fg("dim", "text")         // Very subdued
+theme.fg("success", "text")     // Green
+theme.fg("error", "text")       // Red
+theme.fg("warning", "text")     // Yellow
+theme.fg("border", "─")         // Border color
+theme.bold("text")              // Bold
+
+// Background
+theme.bg("selectedBg", "text")
+theme.bg("toolSuccessBg", "text")
+```
+
+**Full color list:** text, accent, muted, dim, success, error, warning, border, borderAccent, borderMuted, mdHeading, mdLink, mdCode, syntaxKeyword, syntaxString, syntaxComment, etc.
+
+### Theme Change Handling
+
+When the theme changes, `invalidate()` is called. If your component caches themed strings, rebuild them:
+
+```typescript
+class MyComponent extends Container {
+  private message: string;
+  private theme: Theme;
+
+  constructor(message: string, theme: Theme) {
+    super();
+    this.message = message;
+    this.theme = theme;
+    this.rebuild();
+  }
+
+  setTheme(theme: Theme): void {
+    this.theme = theme;
+    this.rebuild();
+  }
+
+  private rebuild(): void {
+    this.clear();
+    // Use current theme colors — will be re-called on theme change
+    this.addChild(new Text(this.theme.fg("accent", this.message), 1, 0));
+  }
+
+  override invalidate(): void {
+    super.invalidate();
+    this.rebuild();
+  }
+}
+```
+
+## Common Patterns
+
+### Bordered Box Helper
+
+```typescript
+protected box(lines: string[], width: number, title?: string): string[] {
+  const th = this.theme;
+  const innerW = Math.max(1, width - 2);
+  const result: string[] = [];
+
+  const titleStr = title ? truncateToWidth(` ${title} `, innerW) : "";
+  const titleW = visibleWidth(titleStr);
+  const topLeft = "─".repeat(Math.floor((innerW - titleW) / 2));
+  const topRight = "─".repeat(Math.max(0, innerW - titleW - topLeft.length));
+  result.push(th.fg("border", `╭${topLeft}`) + th.fg("accent", titleStr) + th.fg("border", `${topRight}╮`));
+
+  for (const line of lines) {
+    result.push(th.fg("border", "│") + truncateToWidth(line, innerW, "…", true) + th.fg("border", "│"));
+  }
+
+  result.push(th.fg("border", `╰${"─".repeat(innerW)}╯`));
+  return result;
+}
+```
+
+### Live-Updating Overlay (~30 FPS)
+
+```typescript
+class LivePanel {
+  private interval: ReturnType<typeof setInterval> | null = null;
+
+  constructor(private tui: TUI, private theme: Theme, private done: () => void) {
+    this.interval = setInterval(() => {
+      this.tui.requestRender();  // Triggers render() call
+    }, 1000 / 30);
+  }
+
+  render(width: number): string[] { /* ... */ }
+  handleInput(data: string): void {
+    if (matchesKey(data, "escape")) { this.dispose(); this.done(); }
+  }
+  invalidate(): void {}
+  dispose(): void {
+    if (this.interval) { clearInterval(this.interval); this.interval = null; }
+  }
+}
+```
+
+### Responsive Sidepanel
+
+```typescript
+await ctx.ui.custom<void>(
+  (tui, theme, _kb, done) => new SidePanel(tui, theme, done),
+  {
+    overlay: true,
+    overlayOptions: {
+      anchor: "right-center",
+      width: "25%",
+      minWidth: 30,
+      margin: { right: 1 },
+      visible: (termWidth) => termWidth >= 100,  // Auto-hide on narrow terminals
+    },
+  }
+);
+```
+
+### Toggle Overlay Visibility
+
+```typescript
+let handle: OverlayHandle | null = null;
+
+await ctx.ui.custom<void>(
+  (tui, theme, _kb, done) => new MyPanel(tui, theme, done),
+  {
+    overlay: true,
+    overlayOptions: { anchor: "right-center", width: "30%" },
+    onHandle: (h) => { handle = h; },
+  }
+);
+
+// Elsewhere (e.g. in a shortcut handler):
+handle?.setHidden(!handle.isHidden());
+```
+
+### Cross-Extension Event-Driven Updates
+
+```typescript
+// In extension init:
+const EVENT_NAME = "my-ext:update";
+pi.events.emit(EVENT_NAME, { status: "active" });
+
+// In overlay constructor:
+this.unsubscribe = pi.events.on(EVENT_NAME, (data) => {
+  this.state = data;
+  this.tui.requestRender();
+});
+
+// In dispose:
+dispose(): void { this.unsubscribe?.(); }
+```
+
+### Shared State via Symbol.for
+
+```typescript
+const STATE_KEY = Symbol.for("pi:my-extension-state");
+
+// Writer
+(globalThis as any)[STATE_KEY] = { count: 0, items: [] };
+
+// Reader (any extension)
+const state = (globalThis as any)[Symbol.for("pi:my-extension-state")];
+```
+
+## Testability Pattern — ThemeFn Bridge
+
+Separate pure rendering logic from pi-tui dependencies for unit testing:
+
+```typescript
+// overlay-data.ts (pure logic, testable)
+type ThemeFn = (color: string, text: string) => string;
+
+export function renderStatusLine(state: MyState, thFn: ThemeFn, width: number): string {
+  return thFn("accent", state.label) + " " + thFn("dim", `${state.count} items`);
+}
+
+// overlay.ts (pi-tui bridge, not unit-tested)
+import type { Theme } from "@cwilson613/pi-coding-agent";
+const thFn: ThemeFn = (color, text) => theme.fg(color as any, text);
+const line = renderStatusLine(state, thFn, width);
+```
+
+In tests, use an identity `thFn`: `const thFn = (_c: string, t: string) => t;`
+
+## Pitfalls
+
+| Pitfall | Fix |
+|---------|-----|
+| Lines exceed `width` | Always `truncateToWidth(line, width)` |
+| Overlay doesn't update | Call `tui.requestRender()` after state changes |
+| Theme colors stale after theme switch | Override `invalidate()` to rebuild themed content |
+| `Ctrl+Shift+D` shortcut doesn't fire | Hardcoded as pi-tui debug key — use a different binding |
+| `stdio: "inherit"` in child process | Use `stdio: "pipe"` — inherit corrupts TUI |
+| Overlay reuse after close | Create fresh instances — overlays dispose on close |
+| `process.stderr.write()` corrupts TUI | Write to a log file instead |
+| Footer `render()` returns wrong line count | Default footer is 2 lines; match or replace entirely |
+| pi-tui imports fail in tests | Mock them, or only test pure logic (ThemeFn pattern) |
+| `ctx.ui.custom()` called without `overlay: true` | Takes over the full screen — usually you want overlay |
+
+## Render Caching Pattern
+
+```typescript
+class CachedComponent {
+  private cachedWidth?: number;
+  private cachedLines?: string[];
+
+  render(width: number): string[] {
+    if (this.cachedLines && this.cachedWidth === width) return this.cachedLines;
+    this.cachedLines = this.computeLines(width);
+    this.cachedWidth = width;
+    return this.cachedLines;
+  }
+
+  invalidate(): void {
+    this.cachedWidth = undefined;
+    this.cachedLines = undefined;
+  }
+}
+```
+
+## IME / Focusable Support
+
+For components with text cursors (CJK input method support):
+
+```typescript
+import { CURSOR_MARKER, type Focusable } from "@cwilson613/pi-tui";
+
+class MyInput implements Component, Focusable {
+  focused = false;
+
+  render(width: number): string[] {
+    const marker = this.focused ? CURSOR_MARKER : "";
+    return [`> ${beforeCursor}${marker}\x1b[7m${atCursor}\x1b[27m${afterCursor}`];
+  }
+}
+```
+
+Container components with embedded inputs must propagate `focused` to child inputs for correct IME cursor positioning.
+
+## Custom Editor
+
+Extend `CustomEditor` (not `Editor`) for vim-mode or alternative key handling:
+
+```typescript
+import { CustomEditor } from "@cwilson613/pi-coding-agent";
+
+class VimEditor extends CustomEditor {
+  private mode: "normal" | "insert" = "insert";
+
+  handleInput(data: string): void {
+    if (this.mode === "insert") { super.handleInput(data); return; }
+    // Normal mode: remap keys, call super.handleInput() for unhandled
+    if (data === "i") { this.mode = "insert"; return; }
+    if (data === "h") { super.handleInput("\x1b[D"); return; }  // Left
+    super.handleInput(data);
+  }
+}
+
+// Register:
+ctx.ui.setEditorComponent((tui, theme, keybindings) => new VimEditor(tui, theme, keybindings));
+ctx.ui.setEditorComponent(undefined);  // Restore default
+```
+
+## Tool Rendering
+
+Tools can customize their display in the chat:
+
+```typescript
+pi.registerTool({
+  name: "my_tool",
+  // ...
+  renderCall: (args, theme) => {
+    return new Text(theme.fg("accent", `Running: ${args.action}`), 1, 0);
+  },
+  renderResult: (result, options, theme) => {
+    if (!options.expanded) return undefined;  // Collapsed = default
+    const mdTheme = getMarkdownTheme();
+    return new Markdown(result.content[0]?.text ?? "", 0, 0, mdTheme);
+  },
+});
+```