feat: 工具层及 mcp 大重构 (#252)

* feat: 第一版大重构

* fix: 修复类型问题

* chore: 更新版本到 1.3.2

* Add brave as alternative WebSearchTool

* fix: 修正顺序

* fix: 修复对穷鬼模式的 auto dream 和 session memory 越过

* feat: 穷鬼模式去除 session-summary

* feat: 创建 builtin-tools 包，搬运所有工具实现

将 src/tools/ 下的全部 60 个工具目录迁移至 packages/builtin-tools/src/tools/，
内部导入路径已更新为 src/ alias 模式。

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* refactor: 更新 src/ 中所有工具引用至 builtin-tools 包，删除 src/tools/

- src/tools.ts 及 178 个 src/ 文件的 import 路径从 ./tools/ 改为 builtin-tools/tools/
- 删除 src/tools/ 整个目录（已迁移至 packages/builtin-tools/）

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* chore: 添加 builtin-tools 路径别名至 tsconfig，更新 bun.lock

- tsconfig.json 新增 builtin-tools/* 和 builtin-tools 路径映射
- 新增 packages/builtin-tools/src 至 include

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* refactor: 为 builtin-tools、mcp-client、agent-tools 添加 @claude-code-best 作用域前缀

所有包名及 import 路径统一添加 @claude-code-best/ 前缀：
- builtin-tools → @claude-code-best/builtin-tools
- mcp-client → @claude-code-best/mcp-client
- agent-tools → @claude-code-best/agent-tools

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: 修复 node 环境没有 bun 的问题

---------

Co-authored-by: Eric-Guo <eric.guocz@gmail.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

packages/@ant/ink/docs/01-getting-started.md

@@ -0,0 +1,176 @@
+# Chapter 1: Getting Started
+
+## Installation
+
+`@anthropic/ink` is a workspace package. It is consumed internally and not published to npm.
+
+```json
+{
+  "dependencies": {
+    "@anthropic/ink": "workspace:*"
+  }
+}
+```
+
+### Peer Dependencies
+
+- `react` ^19.2.4
+- `react-reconciler` ^0.33.0
+
+### Key Dependencies
+
+| Package | Purpose |
+|---------|---------|
+| `chalk` | ANSI color generation |
+| `cli-boxes` | Border style definitions |
+| `get-east-asian-width` | CJK character width measurement |
+| `wrap-ansi` | ANSI-aware word wrapping |
+| `bidi-js` | Bidirectional text support |
+| `lodash-es` | Utility functions (throttle, noop) |
+| `signal-exit` | Process exit handler cleanup |
+| `emoji-regex` | Emoji width handling |
+
+## Basic Rendering
+
+### `render(node, options?)`
+
+The primary entry point. Renders a React element tree to the terminal.
+
+```tsx
+import { render } from '@anthropic/ink'
+import { Box, Text } from '@anthropic/ink'
+
+const { unmount, rerender, waitUntilExit } = await render(
+  <Box>
+    <Text>Hello, World!</Text>
+  </Box>
+)
+```
+
+**Parameters:**
+- `node` -- `ReactNode` to render
+- `options` -- `RenderOptions | NodeJS.WriteStream` (optional)
+
+**Returns:** `Promise<Instance>` with:
+- `rerender(node)` -- Replace the root node
+- `unmount()` -- Unmount and clean up
+- `waitUntilExit()` -- `Promise<void>` that resolves on unmount
+- `cleanup()` -- Remove from instance registry
+
+### `renderSync(node, options?)`
+
+Synchronous version of render. Same API, returns `Instance` directly (no Promise).
+
+```tsx
+import { renderSync } from '@anthropic/ink'
+
+const instance = renderSync(<App />)
+// instance.rerender, instance.unmount, etc.
+```
+
+### `createRoot(options?)`
+
+Creates a managed Ink root without immediately rendering. Similar to `react-dom`'s `createRoot`.
+
+```tsx
+import { createRoot } from '@anthropic/ink'
+
+const root = await createRoot({ exitOnCtrlC: false })
+
+// Later, render into it
+root.render(<App />)
+
+// You can re-render into the same root
+root.render(<DifferentApp />)
+
+// Clean up
+root.unmount()
+```
+
+**Returns:** `Promise<Root>` with:
+- `render(node)` -- Mount or update the tree
+- `unmount()` -- Unmount
+- `waitUntilExit()` -- `Promise<void>`
+
+## RenderOptions
+
+```ts
+type RenderOptions = {
+  /** Output stream. Default: process.stdout */
+  stdout?: NodeJS.WriteStream
+
+  /** Input stream. Default: process.stdin */
+  stdin?: NodeJS.ReadStream
+
+  /** Error stream. Default: process.stderr */
+  stderr?: NodeJS.WriteStream
+
+  /** Handle Ctrl+C to exit. Default: true */
+  exitOnCtrlC?: boolean
+
+  /** Patch console methods to prevent Ink output mixing. Default: true */
+  patchConsole?: boolean
+
+  /** Called after each frame render with timing info. */
+  onFrame?: (event: FrameEvent) => void
+}
+```
+
+## Basic Concepts
+
+### Component Tree
+
+Ink renders React components to a terminal using a custom reconciler. The tree structure maps to terminal output:
+
+```tsx
+<Box flexDirection="column">
+  <Text bold color="green">Header</Text>
+  <Box flexDirection="row" gap={1}>
+    <Text>Left</Text>
+    <Text>Right</Text>
+  </Box>
+</Box>
+```
+
+This produces terminal output with Flexbox layout (via Yoga).
+
+### Rendering Pipeline
+
+1. **React Reconciler** -- Standard React reconciliation; diffs virtual tree
+2. **Yoga Layout** -- Computes Flexbox positions/ sizes for every node
+3. **Render to Output** -- Walks the DOM tree, emits styled text into an `Output` buffer
+4. **Screen Diff** -- Compares new frame against previous frame in a screen buffer
+5. **Terminal Write** -- Emits minimal ANSI escape sequences to update only changed cells
+
+### Module System
+
+Import everything from the package root:
+
+```tsx
+// Core rendering
+import { render, createRoot, renderSync } from '@anthropic/ink'
+
+// Components (base, no theme)
+import { BaseBox, BaseText, ScrollBox, Button, Link, Newline, Spacer } from '@anthropic/ink'
+
+// Theme-aware components (recommended)
+import { Box, Text } from '@anthropic/ink'
+
+// Hooks
+import { useApp, useInput, useTerminalSize, useInterval } from '@anthropic/ink'
+
+// Theme
+import { ThemeProvider, useTheme, color } from '@anthropic/ink'
+
+// Keybindings
+import { useKeybinding, KeybindingProvider } from '@anthropic/ink'
+```
+
+### Naming Convention: Base vs Theme-aware
+
+The package exports both raw and theme-aware versions of core components:
+
+- **`BaseBox`** / **`BaseText`** -- Raw components that only accept raw color values (`rgb(...)`, `#hex`, `ansi:...`, `ansi256(...)`)
+- **`Box`** / **`Text`** -- Theme-aware wrappers that accept both theme keys (`'claude'`, `'success'`, `'error'`) and raw color values
+
+Always prefer the theme-aware versions unless you have a specific reason to use raw components.

packages/@ant/ink/docs/02-layout.md

@@ -0,0 +1,348 @@
+# Chapter 2: Layout System
+
+Ink uses [Yoga](https://yogalayout.com/) (Facebook's cross-platform layout engine) to implement CSS Flexbox in the terminal. Every layout is flexbox-based -- there is no CSS Grid or flow layout.
+
+## Box Component
+
+`Box` is the fundamental layout primitive. It is the terminal equivalent of `<div style="display: flex">`.
+
+```tsx
+import { Box, Text } from '@anthropic/ink'
+
+<Box flexDirection="row" gap={1}>
+  <Text>Left</Text>
+  <Text>Right</Text>
+</Box>
+```
+
+### Box Props (Styles)
+
+All layout props are passed directly as JSX props (no `style={}` wrapper needed):
+
+#### Flex Direction
+
+Controls the main axis direction.
+
+```tsx
+<Box flexDirection="row">...</Box>            // Left to right (default)
+<Box flexDirection="column">...</Box>         // Top to bottom
+<Box flexDirection="row-reverse">...</Box>    // Right to left
+<Box flexDirection="column-reverse">...</Box> // Bottom to top
+```
+
+#### Flex Grow / Shrink / Basis
+
+```tsx
+<Box flexGrow={1}>...</Box>      // Grow to fill available space
+<Box flexShrink={0}>...</Box>    // Don't shrink below intrinsic size
+<Box flexBasis={20}>...</Box>    // Initial size before flex distribution
+<Box flexBasis="50%">...</Box>   // Percentage basis
+```
+
+Default values: `flexGrow={0}`, `flexShrink={1}`, `flexBasis=auto`.
+
+#### Flex Wrap
+
+```tsx
+<Box flexWrap="nowrap">...</Box>       // Single line (default)
+<Box flexWrap="wrap">...</Box>         // Multiple lines
+<Box flexWrap="wrap-reverse">...</Box> // Reverse cross-axis stacking
+```
+
+#### Alignment
+
+```tsx
+<Box alignItems="flex-start">...</Box>  // Cross-axis start
+<Box alignItems="center">...</Box>      // Cross-axis center
+<Box alignItems="flex-end">...</Box>    // Cross-axis end
+<Box alignItems="stretch">...</Box>     // Stretch to fill (default)
+
+<Box alignSelf="flex-start">...</Box>   // Override parent's alignItems
+<Box alignSelf="center">...</Box>
+<Box alignSelf="flex-end">...</Box>
+<Box alignSelf="auto">...</Box>         // Inherit from parent
+```
+
+#### Justify Content
+
+```tsx
+<Box justifyContent="flex-start">...</Box>   // Main-axis start (default)
+<Box justifyContent="flex-end">...</Box>      // Main-axis end
+<Box justifyContent="center">...</Box>        // Center
+<Box justifyContent="space-between">...</Box> // Equal gaps, no edges
+<Box justifyContent="space-around">...</Box>  // Equal gaps with edges
+<Box justifyContent="space-evenly">...</Box>  // Evenly distributed
+```
+
+#### Gap
+
+Spacing between children (only accepts integers):
+
+```tsx
+<Box gap={1}>...</Box>              // Both row and column gap
+<Box columnGap={2}>...</Box>        // Gap between columns only
+<Box rowGap={1}>...</Box>           // Gap between rows only
+```
+
+#### Padding
+
+Inner spacing (only accepts integers):
+
+```tsx
+<Box padding={1}>...</Box>           // All sides
+<Box paddingX={2}>...</Box>          // Left and right
+<Box paddingY={1}>...</Box>          // Top and bottom
+<Box paddingLeft={2}>...</Box>       // Left only
+<Box paddingRight={2}>...</Box>      // Right only
+<Box paddingTop={1}>...</Box>        // Top only
+<Box paddingBottom={1}>...</Box>     // Bottom only
+```
+
+#### Margin
+
+Outer spacing (only accepts integers):
+
+```tsx
+<Box margin={1}>...</Box>            // All sides
+<Box marginX={2}>...</Box>           // Left and right
+<Box marginY={1}>...</Box>           // Top and bottom
+<Box marginLeft={2}>...</Box>        // Left only
+<Box marginRight={2}>...</Box>       // Right only
+<Box marginTop={1}>...</Box>         // Top only
+<Box marginBottom={1}>...</Box>      // Bottom only
+```
+
+> **Note:** Fractional values for padding, margin, and gap are not supported. Ink will emit warnings if non-integer values are used.
+
+#### Width & Height
+
+```tsx
+<Box width={40}>...</Box>           // Fixed 40 characters wide
+<Box height={10}>...</Box>          // Fixed 10 rows tall
+<Box width="50%">...</Box>          // 50% of parent's width
+<Box width="100%">...</Box>         // Full parent width
+```
+
+#### Min/Max Dimensions
+
+```tsx
+<Box minWidth={20}>...</Box>
+<Box maxWidth={80}>...</Box>
+<Box minHeight={5}>...</Box>
+<Box maxHeight={20}>...</Box>
+```
+
+Percentage values are supported: `minWidth="30%"`.
+
+#### Position
+
+```tsx
+<Box position="absolute" top={0} right={0}>...</Box>
+<Box position="absolute" top="10%" left="20%">...</Box>
+<Box position="relative">...</Box>  // Default
+```
+
+Position `absolute` removes the element from normal flow and positions it relative to its nearest positioned ancestor. Useful for overlays.
+
+#### Display
+
+```tsx
+<Box display="flex">...</Box>    // Visible (default)
+<Box display="none">...</Box>    // Hidden (removed from layout)
+```
+
+#### Border
+
+```tsx
+<Box borderStyle="single">...</Box>    // Thin border
+<Box borderStyle="double">...</Box>    // Double-line border
+<Box borderStyle="round">...</Box>     // Rounded corners
+<Box borderStyle="bold">...</Box>      // Bold border
+<Box borderStyle="singleDouble">...</Box>  // Mixed
+<Box borderStyle="doubleSingle">...</Box>  // Mixed
+<Box borderStyle="classic">...</Box>   // ASCII art border
+```
+
+Control individual sides and colors:
+
+```tsx
+<Box
+  borderStyle="single"
+  borderTop={false}           // Hide top border
+  borderBottom={true}         // Show bottom border
+  borderColor="rgb(255,0,0)"  // Red border
+  borderDimColor={true}       // Dim the border
+>
+  ...
+</Box>
+```
+
+Per-side colors:
+
+```tsx
+<Box
+  borderStyle="single"
+  borderTopColor="rgb(255,0,0)"
+  borderBottomColor="ansi:green"
+  borderLeftColor="#0000FF"
+  borderRightColor="ansi256(200)"
+/>
+```
+
+Border text (labels in the border):
+
+```tsx
+<Box
+  borderStyle="round"
+  borderText={{ title: "My Panel", align: "left" }}
+/>
+```
+
+#### Background
+
+```tsx
+<Box backgroundColor="rgb(40,40,40)">...</Box>
+```
+
+#### Overflow
+
+```tsx
+<Box overflow="visible">...</Box>   // Content expands container (default)
+<Box overflow="hidden">...</Box>    // Clip without scrolling
+<Box overflow="scroll">...</Box>    // Enable scrolling (use ScrollBox)
+```
+
+`overflowX` and `overflowY` control each axis independently.
+
+#### Opaque
+
+```tsx
+<Box opaque={true}>...</Box>
+```
+
+Fills the box interior with spaces (using terminal's default background) before rendering children. Useful for absolute-positioned overlays where gaps would otherwise be transparent.
+
+#### NoSelect
+
+```tsx
+<Box noSelect={true}>...</Box>              // Exclude from text selection
+<Box noSelect="from-left-edge">...</Box>    // Exclude from column 0 to box edge
+```
+
+Only affects alt-screen text selection. Useful for gutters (line numbers, diff markers).
+
+## Spacer
+
+`Spacer` fills all available space along the main axis (equivalent to `flexGrow: 1`).
+
+```tsx
+<Box flexDirection="row">
+  <Text>Left</Text>
+  <Spacer />
+  <Text>Right</Text>
+</Box>
+```
+
+## Newline
+
+Inserts line breaks.
+
+```tsx
+<Text>
+  Line 1
+  <Newline />
+  Line 2
+  <Newline count={2} />
+  Line 4 (after double break)
+</Text>
+```
+
+## Layout Examples
+
+### Two-column layout
+
+```tsx
+<Box flexDirection="row" width={80}>
+  <Box width="50%" padding={1}>
+    <Text>Left column</Text>
+  </Box>
+  <Box width="50%" padding={1}>
+    <Text>Right column</Text>
+  </Box>
+</Box>
+```
+
+### Centered content
+
+```tsx
+<Box justifyContent="center" alignItems="center" height={20}>
+  <Text>Centered!</Text>
+</Box>
+```
+
+### Sticky footer
+
+```tsx
+<Box flexDirection="column" height={24}>
+  <Box flexGrow={1}>
+    <Text>Scrollable content area</Text>
+  </Box>
+  <Box>
+    <Text>Status bar at bottom</Text>
+  </Box>
+</Box>
+```
+
+### Bordered panel with title
+
+```tsx
+<Box
+  flexDirection="column"
+  borderStyle="round"
+  borderColor="rgb(87,105,247)"
+  padding={1}
+  width={60}
+>
+  <Text bold>Panel Title</Text>
+  <Text>Panel content goes here.</Text>
+</Box>
+```
+
+## NoSelect
+
+Wraps a region to exclude it from text selection in alt-screen mode. A convenience wrapper around `Box` with `noSelect` set.
+
+```tsx
+import { NoSelect } from '@anthropic/ink'
+
+<Box flexDirection="row">
+  <NoSelect>
+    <Text dimColor>1 │ </Text>
+  </NoSelect>
+  <Text>selectable code here</Text>
+</Box>
+```
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `ReactNode` | - | Content |
+| `fromLeftEdge` | `boolean` | `false` | Extend exclusion from column 0 to box's right edge |
+
+Accepts all `BoxProps` except `noSelect`.
+
+## BaseBox vs ThemedBox
+
+Two versions of Box are exported:
+
+- **`BaseBox`** (imported as `BaseBox`) -- Raw box, color props accept only raw `Color` values
+- **`Box`** (themed, imported as `Box`) -- Theme-aware, color props accept `keyof Theme | Color`
+
+```tsx
+// Raw
+<BaseBox borderStyle="single" borderColor="rgb(255,0,0)" />
+
+// Theme-aware (resolves 'permission' to the current theme's blue)
+<Box borderStyle="single" borderColor="permission" />
+```

packages/@ant/ink/docs/03-text-and-styling.md

@@ -0,0 +1,238 @@
+# Chapter 3: Text & Styling
+
+## Text Component
+
+`Text` renders styled text content. It supports colors, emphasis, and text wrapping.
+
+```tsx
+import { Text } from '@anthropic/ink'
+
+<Text bold color="success">Operation complete</Text>
+```
+
+### Text Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `color` | `keyof Theme \| Color` | - | Foreground color |
+| `backgroundColor` | `keyof Theme` | - | Background color (theme-aware) |
+| `bold` | `boolean` | `false` | Bold text |
+| `dimColor` | `boolean` | `false` | Dim text (uses theme's `inactive` color) |
+| `italic` | `boolean` | `false` | Italic text |
+| `underline` | `boolean` | `false` | Underlined text |
+| `strikethrough` | `boolean` | `false` | Strikethrough text |
+| `inverse` | `boolean` | `false` | Swap foreground/background |
+| `wrap` | `TextWrap` | `'wrap'` | Wrapping/truncation mode |
+| `children` | `ReactNode` | - | Text content |
+
+> **Note:** `bold` and `dimColor` are mutually exclusive (ANSI terminals cannot render both simultaneously).
+
+### BaseText vs ThemedText
+
+- **`BaseText`** -- Accepts raw `Color` values only
+- **`Text`** (default export) -- Theme-aware, accepts `keyof Theme | Color` for `color`, and `keyof Theme` for `backgroundColor`
+
+```tsx
+// Raw color
+<BaseText color="rgb(255,0,0)">Red text</BaseText>
+
+// Theme key (resolved to current theme palette)
+<Text color="error">Error message</Text>
+
+// Mixed
+<Text color="#FF0000">Custom red</Text>
+```
+
+### Text Wrap Modes
+
+```tsx
+<Text wrap="wrap">...</Text>                // Word-wrap at container width (default)
+<Text wrap="wrap-trim">...</Text>           // Wrap + trim trailing whitespace
+<Text wrap="end">...</Text>                 // Truncate with "..." at end
+<Text wrap="truncate-end">...</Text>        // Same as "end"
+<Text wrap="truncate">...</Text>            // Truncate (no ellipsis)
+<Text wrap="middle">...</Text>              // "start...end"
+<Text wrap="truncate-middle">...</Text>     // Same as "middle"
+<Text wrap="truncate-start">...</Text>      // "...text"
+```
+
+### TextHoverColorContext
+
+Uncolored `Text` children inherit a hover color from context:
+
+```tsx
+import { TextHoverColorContext } from '@anthropic/ink'
+
+<TextHoverColorContext.Provider value="suggestion">
+  <Text>Uncolored text gets the suggestion color</Text>
+  <Text color="error">This stays red</Text>
+</TextHoverColorContext.Provider>
+```
+
+Precedence: explicit `color` > `TextHoverColorContext` > `dimColor`.
+
+## Color System
+
+### Raw Color Formats
+
+Four formats are supported for raw color values:
+
+```tsx
+// RGB
+<Text color="rgb(255,107,128)">Bright red</Text>
+
+// Hex
+<Text color="#FF6B80">Bright red</Text>
+
+// ANSI 256-color
+<Text color="ansi256(196)">Red from 256-color palette</Text>
+
+// Named ANSI 16-color
+<Text color="ansi:red">Red</Text>
+<Text color="ansi:greenBright">Bright green</Text>
+```
+
+### ANSI Named Colors
+
+Full list of `ansi:` prefixed names:
+
+| Name | Color |
+|------|-------|
+| `ansi:black` | Black |
+| `ansi:red` | Red |
+| `ansi:green` | Green |
+| `ansi:yellow` | Yellow |
+| `ansi:blue` | Blue |
+| `ansi:magenta` | Magenta |
+| `ansi:cyan` | Cyan |
+| `ansi:white` | White |
+| `ansi:blackBright` | Dark gray |
+| `ansi:redBright` | Bright red |
+| `ansi:greenBright` | Bright green |
+| `ansi:yellowBright` | Bright yellow |
+| `ansi:blueBright` | Bright blue |
+| `ansi:magentaBright` | Bright magenta |
+| `ansi:cyanBright` | Bright cyan |
+| `ansi:whiteBright` | Bright white |
+
+## Utility Functions
+
+### `color(colorValue, themeName, type?)`
+
+Curried theme-aware color function. Resolves theme keys to raw color values.
+
+```tsx
+import { color } from '@anthropic/ink'
+
+const paint = color('error', 'dark')  // Returns (text: string) => string
+console.log(paint('failed'))          // 'failed' wrapped in ANSI red codes
+
+const paintFg = color('rgb(255,0,0)', 'dark', 'foreground')
+const paintBg = color('success', 'dark', 'background')
+```
+
+Parameters:
+- `c` -- `keyof Theme | Color | undefined` -- Theme key or raw color
+- `theme` -- `ThemeName` -- Current theme
+- `type` -- `'foreground' | 'background'` (default `'foreground'`)
+
+### `stringWidth(text)`
+
+Measures the visual width of a string in terminal columns, accounting for:
+- CJK characters (2 columns each)
+- Emoji (2 columns each)
+- ANSI escape sequences (0 columns)
+
+```tsx
+import { stringWidth } from '@anthropic/ink'
+
+stringWidth('hello')      // 5
+stringWidth('你好')        // 4
+stringWidth('\x1b[31mhi')  // 2 (ANSI codes ignored)
+```
+
+### `wrapText(text, width, textWrap)`
+
+Wraps text to a given width with the specified wrapping mode.
+
+```tsx
+import { wrapText } from '@anthropic/ink'
+
+wrapText('Hello World', 5, 'wrap')    // 'Hello\nWorld'
+wrapText('Hello World', 8, 'end')     // 'Hello...'
+```
+
+### `wrapAnsi(text, width)`
+
+Wraps text containing ANSI escape codes while preserving styling.
+
+```tsx
+import { wrapAnsi } from '@anthropic/ink'
+
+wrapAnsi('\x1b[31mHello World\x1b[0m', 5)
+// Wraps at word boundaries, keeps color codes intact
+```
+
+### `measureElement(node)`
+
+Measures a rendered DOM element's dimensions.
+
+```tsx
+import { measureElement } from '@anthropic/ink'
+
+const { width, height } = measureElement(domElement)
+```
+
+## Link Component
+
+Renders an OSC 8 terminal hyperlink (clickable URL in supported terminals).
+
+```tsx
+import { Link } from '@anthropic/ink'
+
+<Link url="https://example.com">
+  <Text underline color="suggestion">example.com</Text>
+</Link>
+```
+
+Props:
+- `url` -- `string` (required) -- Target URL
+- `children` -- `ReactNode` -- Display content
+- `fallback` -- `ReactNode` -- Shown when hyperlinks are unsupported
+
+## RawAnsi Component
+
+Renders pre-formatted ANSI strings directly into the layout.
+
+```tsx
+import { RawAnsi } from '@anthropic/ink'
+
+<RawAnsi
+  lines={['\x1b[31mRed line 1\x1b[0m', '\x1b[32mGreen line 2\x1b[0m']}
+  width={40}
+/>
+```
+
+Props:
+- `lines` -- `string[]` -- Pre-rendered ANSI lines (one terminal row each)
+- `width` -- `number` -- Column width the producer wrapped to
+
+## Border Rendering
+
+### `renderBorder(box, output, options?)`
+
+Low-level border rendering function used internally by Box.
+
+```tsx
+import { renderBorder } from '@anthropic/ink'
+import type { BorderTextOptions } from '@anthropic/ink'
+```
+
+Border styles available (from `cli-boxes`):
+- `single` -- Thin lines `─│┌┐└┘`
+- `double` -- Double lines `═║╔╗╚╝`
+- `round` -- Rounded corners `─│╭╮╰╯`
+- `bold` -- Bold lines `━┃┏┓┗┛`
+- `singleDouble` -- Single horizontal, double vertical
+- `doubleSingle` -- Double horizontal, single vertical
+- `classic` -- ASCII `─|++++`

packages/@ant/ink/docs/04-theme-system.md

@@ -0,0 +1,213 @@
+# Chapter 4: Theme System
+
+The theme system provides consistent, accessible color palettes across the application. It supports dark mode, light mode, ANSI-only terminals, and colorblind-accessible variants.
+
+## ThemeProvider
+
+Wraps the application to provide theme context.
+
+```tsx
+import { ThemeProvider } from '@anthropic/ink'
+
+function App() {
+  return (
+    <ThemeProvider initialState="dark" onThemeSave={(setting) => saveConfig(setting)}>
+      <MyComponent />
+    </ThemeProvider>
+  )
+}
+```
+
+### Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `children` | `ReactNode` | Child components |
+| `initialState` | `ThemeSetting` | Initial theme (default: loads from config) |
+| `onThemeSave` | `(setting: ThemeSetting) => void` | Called when theme is saved |
+
+### Theme Configuration Injection
+
+Before mounting, inject config persistence callbacks:
+
+```tsx
+import { setThemeConfigCallbacks } from '@anthropic/ink'
+
+setThemeConfigCallbacks({
+  loadTheme: () => configStore.get('theme', 'dark'),
+  saveTheme: (setting) => configStore.set('theme', setting),
+})
+```
+
+## Theme Settings
+
+```ts
+type ThemeSetting = 'auto' | 'dark' | 'light' | 'light-daltonized' | 'dark-daltonized' | 'light-ansi' | 'dark-ansi'
+type ThemeName = 'dark' | 'light' | 'light-daltonized' | 'dark-daltonized' | 'light-ansi' | 'dark-ansi'
+```
+
+| Theme | Description |
+|-------|-------------|
+| `dark` | Dark theme with RGB colors (default) |
+| `light` | Light theme with RGB colors |
+| `dark-daltonized` | Colorblind-accessible dark theme |
+| `light-daltonized` | Colorblind-accessible light theme |
+| `dark-ansi` | Dark theme using only 16 ANSI colors |
+| `light-ansi` | Light theme using only 16 ANSI colors |
+| `auto` | Follows terminal's dark/light mode (resolved at runtime) |
+
+## Theme Hooks
+
+### `useTheme()`
+
+Returns the resolved theme name and setter.
+
+```tsx
+const [currentTheme, setTheme] = useTheme()
+// currentTheme: ThemeName (never 'auto')
+// setTheme: (setting: ThemeSetting) => void
+```
+
+### `useThemeSetting()`
+
+Returns the raw setting (may be `'auto'`).
+
+```tsx
+const setting = useThemeSetting()  // 'auto' | 'dark' | ...
+```
+
+### `usePreviewTheme()`
+
+Returns preview controls for a theme picker UI.
+
+```tsx
+const { setPreviewTheme, savePreview, cancelPreview } = usePreviewTheme()
+
+// Show preview
+setPreviewTheme('light')
+
+// User confirms
+savePreview()
+
+// User cancels
+cancelPreview()
+```
+
+## Theme Color Palette
+
+Every theme defines these semantic color keys:
+
+### Brand & Identity
+
+| Key | Purpose |
+|-----|---------|
+| `claude` | Brand orange |
+| `claudeShimmer` | Lighter brand orange (animated) |
+| `permission` | Permission/blue |
+| `permissionShimmer` | Lighter permission blue |
+| `autoAccept` | Electric violet |
+| `planMode` | Teal/sage |
+| `ide` | Muted blue |
+
+### Semantic Colors
+
+| Key | Purpose |
+|-----|---------|
+| `text` | Primary text color |
+| `inverseText` | Text on inverse backgrounds |
+| `inactive` | Dimmed/disabled elements |
+| `inactiveShimmer` | Lighter inactive |
+| `subtle` | Very subtle text |
+| `suggestion` | Interactive/accent |
+| `background` | General background accent |
+| `success` | Positive/success |
+| `error` | Negative/error |
+| `warning` | Caution/warning |
+| `warningShimmer` | Lighter warning |
+| `merged` | Merged state |
+
+### Diff Colors
+
+| Key | Purpose |
+|-----|---------|
+| `diffAdded` | Added lines background |
+| `diffRemoved` | Removed lines background |
+| `diffAddedDimmed` | Dimmed added |
+| `diffRemovedDimmed` | Dimmed removed |
+| `diffAddedWord` | Word-level added |
+| `diffRemovedWord` | Word-level removed |
+
+### UI Colors
+
+| Key | Purpose |
+|-----|---------|
+| `promptBorder` | Input prompt border |
+| `promptBorderShimmer` | Lighter prompt border |
+| `bashBorder` | Shell block border |
+| `selectionBg` | Text selection highlight background |
+| `userMessageBackground` | User message background |
+| `userMessageBackgroundHover` | User message hover |
+| `messageActionsBackground` | Action buttons background |
+
+### Agent Colors
+
+| Key | Purpose |
+|-----|---------|
+| `red_FOR_SUBAGENTS_ONLY` | Agent color assignment |
+| `blue_FOR_SUBAGENTS_ONLY` | Agent color assignment |
+| `green_FOR_SUBAGENTS_ONLY` | Agent color assignment |
+| `yellow_FOR_SUBAGENTS_ONLY` | Agent color assignment |
+| `purple_FOR_SUBAGENTS_ONLY` | Agent color assignment |
+| `orange_FOR_SUBAGENTS_ONLY` | Agent color assignment |
+| `pink_FOR_SUBAGENTS_ONLY` | Agent color assignment |
+| `cyan_FOR_SUBAGENTS_ONLY` | Agent color assignment |
+
+## Using Theme Colors in Components
+
+### ThemedText
+
+```tsx
+<Text color="success">Operation complete</Text>
+<Text color="error" bold>Failed!</Text>
+<Text color="claude">Claude says...</Text>
+<Text dimColor>Secondary info</Text>
+<Text backgroundColor="userMessageBackground">Highlighted</Text>
+```
+
+### ThemedBox
+
+```tsx
+<Box borderStyle="single" borderColor="permission" backgroundColor="userMessageBackground">
+  <Text>Themed content</Text>
+</Box>
+```
+
+### color() Utility
+
+```tsx
+import { color, useTheme } from '@anthropic/ink'
+
+function MyComponent() {
+  const [themeName] = useTheme()
+  const paint = color('success', themeName)
+  // paint('text') returns ANSI-colored string
+}
+```
+
+## Daltonized Themes
+
+The daltonized themes (`light-daltonized`, `dark-daltonized`) are designed for users with protanopia/deuteranopia:
+
+- Green/red diffs replaced with blue/red
+- Status colors use blue instead of green
+- Warning colors adjusted for better distinction
+- All color pairs verified for sufficient contrast
+
+## System Theme Detection
+
+When `ThemeSetting` is `'auto'`:
+
+1. Seeds from `$COLORFGBG` environment variable
+2. Queries terminal via OSC 11 for live background color
+3. Watches for changes (terminal theme switch) in real-time
+4. Resolves to `'dark'` or `'light'` based on detected brightness

packages/@ant/ink/docs/05-design-system.md

@@ -0,0 +1,390 @@
+# Chapter 5: Design System Components
+
+Pre-built theme-aware UI components for common terminal interface patterns.
+
+## Dialog
+
+Modal dialog with border, title, and keyboard navigation.
+
+```tsx
+import { Dialog } from '@anthropic/ink'
+
+<Dialog
+  title="Confirm Action"
+  subtitle="This cannot be undone"
+  onCancel={() => setShowDialog(false)}
+  color="warning"
+>
+  <Text>Are you sure you want to proceed?</Text>
+</Dialog>
+```
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `title` | `ReactNode` | - | Dialog title (required) |
+| `subtitle` | `ReactNode` | - | Optional subtitle |
+| `children` | `ReactNode` | - | Dialog body content |
+| `onCancel` | `() => void` | - | Called on Esc/n (required) |
+| `color` | `keyof Theme` | `'permission'` | Title and border color |
+| `hideInputGuide` | `boolean` | `false` | Hide the keyboard hint footer |
+| `hideBorder` | `boolean` | `false` | Render without Pane border |
+| `inputGuide` | `(exitState) => ReactNode` | - | Custom input guide footer |
+| `isCancelActive` | `boolean` | `true` | Enable/disable cancel keybindings |
+
+### Keyboard Shortcuts
+
+- **Enter** -- Confirm (consumer handles this)
+- **Esc / n** -- Cancel (calls `onCancel`)
+- **Ctrl+C / Ctrl+D** -- Double-press to exit
+
+### Custom Input Guide
+
+```tsx
+<Dialog
+  title="Save file?"
+  onCancel={handleCancel}
+  inputGuide={(exitState) => (
+    exitState.pending
+      ? <Text>Press {exitState.keyName} again to exit</Text>
+      : <Text>Press Enter to save, Esc to cancel</Text>
+  )}
+>
+  ...
+</Dialog>
+```
+
+## Pane
+
+Bordered container with themed top border.
+
+```tsx
+import { Pane } from '@anthropic/ink'
+
+<Pane color="permission">
+  <Text>Content inside a bordered pane</Text>
+</Pane>
+```
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `ReactNode` | - | Content |
+| `color` | `keyof Theme` | `'permission'` | Top border color |
+
+## ProgressBar
+
+Visual progress indicator.
+
+```tsx
+import { ProgressBar } from '@anthropic/ink'
+
+<ProgressBar
+  ratio={0.65}
+  width={40}
+  fillColor="rate_limit_fill"
+  emptyColor="rate_limit_empty"
+/>
+```
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `ratio` | `number` | - | Progress 0..1 (required) |
+| `width` | `number` | - | Character width (required) |
+| `fillColor` | `keyof Theme` | - | Filled portion color |
+| `emptyColor` | `keyof Theme` | - | Empty portion color |
+
+## Spinner
+
+Animated loading spinner. No props.
+
+```tsx
+import { Spinner } from '@anthropic/ink'
+
+<Box gap={1}>
+  <Spinner />
+  <Text>Loading...</Text>
+</Box>
+```
+
+## LoadingState
+
+Loading message with spinner and optional subtitle.
+
+```tsx
+import { LoadingState } from '@anthropic/ink'
+
+<LoadingState
+  message="Installing dependencies"
+  subtitle="This may take a moment"
+  bold={true}
+/>
+```
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `message` | `string` | - | Loading message (required) |
+| `bold` | `boolean` | `false` | Bold message |
+| `dimColor` | `boolean` | `false` | Dimmed message |
+| `subtitle` | `string` | - | Secondary text below |
+
+## StatusIcon
+
+Semantic status indicator with icon and color.
+
+```tsx
+import { StatusIcon } from '@anthropic/ink'
+
+<StatusIcon status="success" withSpace />
+<Text>Build complete</Text>
+```
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `status` | `'success' \| 'error' \| 'warning' \| 'info' \| 'pending' \| 'loading'` | - | Status type (required) |
+| `withSpace` | `boolean` | `false` | Add trailing space |
+
+Status icons:
+- `success` -- Green checkmark
+- `error` -- Red cross
+- `warning` -- Yellow warning
+- `info` -- Blue info
+- `pending` -- Dimmed circle
+- `loading` -- Dimmed ellipsis
+
+## FuzzyPicker
+
+Full-featured fuzzy search selector with preview support.
+
+```tsx
+import { FuzzyPicker } from '@anthropic/ink'
+
+<FuzzyPicker
+  title="Select a file"
+  items={files}
+  getKey={(f) => f.path}
+  renderItem={(f, focused) => <Text>{f.name}</Text>}
+  onQueryChange={(q) => setFilteredFiles(filterFiles(q))}
+  onSelect={(f) => openFile(f)}
+  onCancel={() => setShowPicker(false)}
+/>
+```
+
+### Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `title` | `string` | Picker title (required) |
+| `items` | `readonly T[]` | Items to display (required) |
+| `getKey` | `(item: T) => string` | Unique key extractor (required) |
+| `renderItem` | `(item: T, isFocused: boolean) => ReactNode` | Item renderer (required) |
+| `onQueryChange` | `(query: string) => void` | Filter callback (required) |
+| `onSelect` | `(item: T) => void` | Enter key handler (required) |
+| `onCancel` | `() => void` | Esc handler (required) |
+| `renderPreview` | `(item: T) => ReactNode` | Preview panel renderer |
+| `previewPosition` | `'bottom' \| 'right'` | Preview placement |
+| `visibleCount` | `number` | Max visible items |
+| `direction` | `'down' \| 'up'` | Item ordering |
+| `onTab` | `PickerAction<T>` | Tab key handler |
+| `onShiftTab` | `PickerAction<T>` | Shift+Tab handler |
+| `onFocus` | `(item: T \| undefined) => void` | Focus change callback |
+| `emptyMessage` | `string \| ((query: string) => string)` | Empty state message |
+| `matchLabel` | `string` | Status line below list |
+| `placeholder` | `string` | Input placeholder |
+| `initialQuery` | `string` | Initial search query |
+| `selectAction` | `string` | Action label for byline |
+| `extraHints` | `ReactNode` | Additional keyboard hints |
+
+## Tabs / Tab
+
+Tabbed interface with keyboard navigation.
+
+```tsx
+import { Tabs, Tab } from '@anthropic/ink'
+
+<Tabs title="Settings" color="claude">
+  <Tab title="General" id="general">
+    <GeneralSettings />
+  </Tab>
+  <Tab title="Advanced" id="advanced">
+    <AdvancedSettings />
+  </Tab>
+</Tabs>
+```
+
+### Tabs Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `ReactElement<TabProps>[]` | - | Tab elements |
+| `title` | `string` | - | Header title |
+| `color` | `keyof Theme` | - | Active tab indicator color |
+| `defaultTab` | `string` | - | Initial tab id |
+| `selectedTab` | `string` | - | Controlled selected tab |
+| `onTabChange` | `(tabId: string) => void` | - | Tab change callback |
+| `hidden` | `boolean` | `false` | Hide tab headers |
+| `useFullWidth` | `boolean` | `false` | Use full terminal width |
+| `banner` | `ReactNode` | - | Banner below tab headers |
+| `disableNavigation` | `boolean` | `false` | Disable keyboard nav |
+| `initialHeaderFocused` | `boolean` | `true` | Start with header focused |
+| `contentHeight` | `number` | - | Fixed content height |
+| `navFromContent` | `boolean` | `false` | Allow Tab/Arrow from content |
+
+### Tab Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `title` | `string` | Tab label (required) |
+| `id` | `string` | Tab identifier |
+| `children` | `ReactNode` | Tab content |
+
+### Tab Hooks
+
+```tsx
+import { useTabsWidth, useTabHeaderFocus } from '@anthropic/ink'
+
+const width = useTabsWidth()          // Available content width
+const focused = useTabHeaderFocus()   // Whether tab header is focused
+```
+
+## ListItem
+
+Selectable list item with focus/selection indicators.
+
+```tsx
+import { ListItem } from '@anthropic/ink'
+
+<ListItem isFocused={index === focusedIndex} isSelected={item.checked}>
+  <Text>{item.label}</Text>
+</ListItem>
+```
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `isFocused` | `boolean` | - | Keyboard focus (required) |
+| `isSelected` | `boolean` | `false` | Checked/active state |
+| `children` | `ReactNode` | - | Content |
+| `description` | `string` | - | Secondary text below |
+| `styled` | `boolean` | `true` | Auto-style based on state |
+| `disabled` | `boolean` | `false` | Dimmed, non-interactive |
+| `showScrollDown` | `boolean` | `false` | Scroll-down hint arrow |
+| `showScrollUp` | `boolean` | `false` | Scroll-up hint arrow |
+| `declareCursor` | `boolean` | `true` | Declare terminal cursor |
+
+## SearchBox
+
+Search input with theme-aware styling.
+
+```tsx
+import { SearchBox } from '@anthropic/ink'
+
+<SearchBox
+  query={searchQuery}
+  placeholder="Search..."
+  isFocused={true}
+  isTerminalFocused={true}
+  width="100%"
+/>
+```
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `query` | `string` | - | Current search text |
+| `placeholder` | `string` | - | Placeholder text |
+| `isFocused` | `boolean` | - | Focus state |
+| `isTerminalFocused` | `boolean` | - | Terminal focus state |
+| `prefix` | `string` | - | Input prefix label |
+| `width` | `number \| string` | - | Input width |
+| `cursorOffset` | `number` | - | Cursor position offset |
+| `borderless` | `boolean` | `false` | Remove border |
+
+## Divider
+
+Horizontal/vertical divider line.
+
+```tsx
+import { Divider } from '@anthropic/ink'
+
+<Divider width={60} color="subtle" />
+<Divider title="Section Title" />
+```
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `width` | `number` | Terminal width | Divider width |
+| `color` | `keyof Theme` | Dimmed | Line color |
+| `char` | `string` | `'─'` | Line character |
+| `padding` | `number` | `0` | Width reduction |
+| `title` | `string` | - | Centered title text |
+
+## Byline
+
+Footer with middot-separated items.
+
+```tsx
+import { Byline } from '@anthropic/ink'
+
+<Byline>
+  <KeyboardShortcutHint shortcut="Enter" action="confirm" />
+  <KeyboardShortcutHint shortcut="Esc" action="cancel" />
+</Byline>
+```
+
+## KeyboardShortcutHint
+
+Display a keyboard shortcut with its action.
+
+```tsx
+import { KeyboardShortcutHint } from '@anthropic/ink'
+
+<KeyboardShortcutHint shortcut="Enter" action="confirm" />
+<KeyboardShortcutHint shortcut="↑/↓" action="navigate" parens />
+```
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `shortcut` | `string` | - | Key or chord to display |
+| `action` | `string` | - | Action description |
+| `parens` | `boolean` | `false` | Wrap in parentheses |
+| `bold` | `boolean` | `false` | Bold shortcut text |
+
+## ConfigurableShortcutHint
+
+Displays a shortcut hint that reads the actual keybinding from config.
+
+```tsx
+import { ConfigurableShortcutHint } from '@anthropic/ink'
+
+<ConfigurableShortcutHint
+  action="confirm:no"
+  context="Confirmation"
+  fallback="Esc"
+  description="cancel"
+/>
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `action` | `string` | Keybinding action name |
+| `context` | `string` | Keybinding context |
+| `fallback` | `string` | Default shortcut if unbound |
+| `description` | `string` | Action description |
+| `parens` | `boolean` | Wrap in parentheses |
+| `bold` | `boolean` | Bold shortcut text |
+
+## Ratchet
+
+Animated counter component that prevents layout jumps.
+
+```tsx
+import { Ratchet } from '@anthropic/ink'
+
+<Ratchet lock="always">
+  <Text>{count}</Text>
+</Ratchet>
+```
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `ReactNode` | - | Content |
+| `lock` | `'always' \| 'offscreen'` | `'always'` | Width locking strategy. `'always'` locks always; `'offscreen'` only locks when the element is scrolled off-screen |

packages/@ant/ink/docs/06-scrolling.md

@@ -0,0 +1,189 @@
+# Chapter 6: Scrolling
+
+## ScrollBox
+
+A scrollable container with imperative scroll API, viewport culling, and sticky scroll support.
+
+```tsx
+import { ScrollBox } from '@anthropic/ink'
+import type { ScrollBoxHandle } from '@anthropic/ink'
+
+function MessageList({ messages }) {
+  const scrollRef = useRef<ScrollBoxHandle>(null)
+
+  // Auto-scroll to bottom on new messages
+  useEffect(() => {
+    scrollRef.current?.scrollToBottom()
+  }, [messages.length])
+
+  return (
+    <ScrollBox ref={scrollRef} stickyScroll flexDirection="column" height={20}>
+      {messages.map(msg => (
+        <Text key={msg.id}>{msg.text}</Text>
+      ))}
+    </ScrollBox>
+  )
+}
+```
+
+### Props
+
+ScrollBox accepts all Box layout props except `textWrap`, `overflow`, `overflowX`, `overflowY` (these are managed internally):
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `ref` | `Ref<ScrollBoxHandle>` | - | Imperative handle |
+| `stickyScroll` | `boolean` | `false` | Auto-follow new content |
+| *(layout props)* | `Styles` | - | Width, height, padding, etc. |
+
+### ScrollBoxHandle (Imperative API)
+
+```ts
+interface ScrollBoxHandle {
+  // Absolute positioning
+  scrollTo(y: number): void
+  scrollToElement(el: DOMElement, offset?: number): void
+  scrollToBottom(): void
+
+  // Relative positioning
+  scrollBy(dy: number): void
+
+  // Query state
+  getScrollTop(): number
+  getPendingDelta(): number
+  getScrollHeight(): number
+  getFreshScrollHeight(): number
+  getViewportHeight(): number
+  getViewportTop(): number
+  isSticky(): boolean
+
+  // Events
+  subscribe(listener: () => void): () => void
+
+  // Virtual scroll support
+  setClampBounds(min?: number, max?: number): void
+}
+```
+
+### Method Details
+
+#### `scrollTo(y)`
+
+Jump to an absolute position. Breaks sticky scroll.
+
+```tsx
+scrollRef.current?.scrollTo(0)  // Scroll to top
+```
+
+#### `scrollBy(dy)`
+
+Scroll by a relative amount. Accumulates deltas for smooth scrolling.
+
+```tsx
+scrollRef.current?.scrollBy(3)   // Scroll down 3 rows
+scrollRef.current?.scrollBy(-5)  // Scroll up 5 rows
+```
+
+#### `scrollToElement(el, offset?)`
+
+Scroll so a specific DOM element is at the viewport top. More reliable than `scrollTo` because it reads the element's position at render time (avoids stale layout values).
+
+```tsx
+const elementRef = useRef<DOMElement>(null)
+scrollRef.current?.scrollToElement(elementRef.current!, 2)
+```
+
+#### `scrollToBottom()`
+
+Pin scroll to bottom. Enables sticky mode.
+
+```tsx
+scrollRef.current?.scrollToBottom()
+```
+
+#### `isSticky()`
+
+Returns `true` when scroll is pinned to the bottom.
+
+```tsx
+if (scrollRef.current?.isSticky()) {
+  // User hasn't scrolled up
+}
+```
+
+#### `subscribe(listener)`
+
+Subscribe to imperative scroll changes. Returns unsubscribe function.
+
+```tsx
+useEffect(() => {
+  return scrollRef.current?.subscribe(() => {
+    console.log('Scroll position changed')
+  })
+}, [])
+```
+
+### Sticky Scroll
+
+When `stickyScroll` is enabled:
+
+1. Scroll automatically follows new content at the bottom
+2. User scroll (via `scrollBy`/`scrollTo`) breaks stickiness
+3. `scrollToBottom()` re-enables stickiness
+4. Content growth at the bottom is detected and followed automatically
+
+```tsx
+<ScrollBox stickyScroll height={20}>
+  {/* New items auto-scroll to bottom */}
+  {items.map(renderItem)}
+</ScrollBox>
+```
+
+### Viewport Culling
+
+ScrollBox only renders children that intersect the visible viewport. Children outside the viewport are still mounted in React but skipped during terminal rendering. This makes large lists performant.
+
+### Virtual Scrolling
+
+For very large lists, use `setClampBounds` in combination with a virtual scrolling hook:
+
+```tsx
+const scrollRef = useRef<ScrollBoxHandle>(null)
+
+// After computing visible range
+scrollRef.current?.setClampBounds(firstVisibleRow, lastVisibleRow)
+```
+
+This prevents burst `scrollTo` calls from showing blank space beyond mounted content.
+
+### Scroll Events
+
+ScrollBox bypasses React state for scroll operations. Instead:
+1. `scrollTo`/`scrollBy` mutate `scrollTop` directly on the DOM node
+2. The node is marked dirty
+3. A microtask-deferred render fires to coalesce multiple scroll events
+4. The Ink renderer reads `scrollTop` during layout
+
+This avoids React reconciler overhead per wheel event.
+
+### Integration with Mouse Wheel
+
+In alt-screen mode, mouse wheel events are captured by the `App` component and forwarded to the focused ScrollBox:
+
+```
+Wheel event → App.handleMouseEvent → ScrollBox.scrollBy(delta)
+```
+
+### Layout Structure
+
+ScrollBox creates a two-level DOM structure:
+
+```
+ink-box (overflow: scroll, constrained height)
+└── Box (flexGrow: 1, flexShrink: 0, width: 100%)
+    ├── Child 1
+    ├── Child 2
+    └── ...
+```
+
+The outer `ink-box` is the viewport with constrained size. The inner `Box` grows to fit all content. The renderer computes `scrollHeight` from the inner box and translates content by `-scrollTop`.

packages/@ant/ink/docs/07-user-input.md

@@ -0,0 +1,267 @@
+# Chapter 7: User Input
+
+## useInput
+
+The primary hook for handling keyboard input.
+
+```tsx
+import { useInput } from '@anthropic/ink'
+
+function MyComponent() {
+  useInput((input, key, event) => {
+    if (input === 'q') {
+      // 'q' key pressed
+    }
+    if (key.leftArrow) {
+      // Left arrow
+    }
+    if (key.ctrl && input === 'c') {
+      // Ctrl+C (only if exitOnCtrlC is false)
+    }
+    if (key.meta && input === 'b') {
+      // Alt+B (Option+B on Mac)
+    }
+    if (key.shift && input === 'Tab') {
+      // Shift+Tab
+    }
+  })
+
+  return <Text>Press keys...</Text>
+}
+```
+
+### Signature
+
+```ts
+function useInput(
+  handler: (input: string, key: Key, event: InputEvent) => void,
+  options?: { isActive?: boolean }
+): void
+```
+
+### Parameters
+
+- **`input`** (`string`) -- The character entered. Empty string for non-printable keys (arrows, function keys). For paste events, the entire pasted text.
+- **`key`** (`Key`) -- Parsed key metadata (see below)
+- **`event`** (`InputEvent`) -- Raw event with `stopImmediatePropagation()`
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `isActive` | `boolean` | `true` | Enable/disable input handling |
+
+### Key Object
+
+```ts
+type Key = {
+  upArrow: boolean
+  downArrow: boolean
+  leftArrow: boolean
+  rightArrow: boolean
+  pageDown: boolean
+  pageUp: boolean
+  wheelUp: boolean       // Mouse wheel in alt-screen
+  wheelDown: boolean      // Mouse wheel in alt-screen
+  home: boolean
+  end: boolean
+  return: boolean
+  escape: boolean
+  ctrl: boolean
+  shift: boolean
+  fn: boolean
+  tab: boolean
+  backspace: boolean
+  delete: boolean
+  meta: boolean           // Alt / Option
+  super: boolean          // Cmd (macOS) / Win key
+}
+```
+
+### Event Propagation
+
+Multiple `useInput` handlers form a chain. Call `event.stopImmediatePropagation()` to prevent downstream handlers from receiving the event:
+
+```tsx
+useInput((input, key, event) => {
+  if (input === 'j') {
+    // Consumed by this handler
+    event.stopImmediatePropagation()
+  }
+  // Other handlers won't see 'j'
+})
+
+useInput((input, key) => {
+  // This won't fire for 'j'
+})
+```
+
+### Raw Mode
+
+`useInput` automatically enables raw mode on stdin when active. Raw mode is reference-counted -- it stays enabled as long as any hook has `isActive: true`.
+
+In raw mode:
+- Keystrokes don't echo
+- Ctrl+C is not sent as signal (app must handle it)
+- Line buffering is disabled
+
+## InputEvent
+
+```ts
+class InputEvent extends Event {
+  readonly input: string
+  readonly key: Key
+  readonly keypress: ParsedKey  // Raw parsed keypress data
+}
+```
+
+## KeyboardEvent
+
+DOM-like keyboard event dispatched to focused elements:
+
+```ts
+class KeyboardEvent extends Event {
+  readonly key: Key
+}
+```
+
+Used with `Box`'s `onKeyDown` and `onKeyDownCapture` props:
+
+```tsx
+<Box
+  tabIndex={0}
+  autoFocus
+  onKeyDown={(event) => {
+    if (event.key.return) {
+      handleSubmit()
+    }
+  }}
+>
+  <Text>Press Enter to submit</Text>
+</Box>
+```
+
+## Key Parsing
+
+Ink supports multiple keyboard protocols:
+
+### Standard Escape Sequences
+- Arrow keys, function keys, Home/End, Page Up/Down
+- Ctrl+letter combinations
+- Shift, Alt, Meta modifiers
+
+### Kitty Keyboard Protocol (CSI u)
+Extended key reporting with full modifier support:
+- Distinguishes Ctrl+Shift+A from Ctrl+A
+- Reports Super (Cmd/Win) key
+- Sends key release events
+
+### xterm modifyOtherKeys
+Alternative extended key reporting for xterm-compatible terminals.
+
+### Application Keypad Mode
+Numpad keys mapped to their digit characters.
+
+## Paste Detection
+
+When `Bracketed Paste` mode is enabled (DECSET 2004), pasted text is delivered as a single `InputEvent` with the full text in `input`. This distinguishes paste from rapid typing:
+
+```tsx
+useInput((input, key, event) => {
+  if (event.keypress.paste) {
+    // User pasted text -- handle as a batch
+    handlePaste(input)
+  } else {
+    // Regular keypress
+    handleKey(input, key)
+  }
+})
+```
+
+## Mouse Events (Alt-Screen Only)
+
+In alternate screen mode, mouse events are parsed and dispatched:
+
+### Click Events
+
+```tsx
+<Box
+  onClick={(event) => {
+    console.log(`Clicked at (${event.x}, ${event.y})`)
+    event.stopImmediatePropagation()
+  }}
+>
+  <Text>Click me</Text>
+</Box>
+```
+
+### Hover Events
+
+```tsx
+<Box
+  onMouseEnter={() => setHovered(true)}
+  onMouseLeave={() => setHovered(false)}
+>
+  <Text>{hovered ? 'Hovered!' : 'Hover me'}</Text>
+</Box>
+```
+
+Hover events use `mouseenter`/`mouseleave` semantics (no bubbling between children).
+
+### Wheel Events
+
+Mouse wheel events arrive as `Key.wheelUp`/`Key.wheelDown`:
+
+```tsx
+useInput((input, key) => {
+  if (key.wheelUp) scrollUp()
+  if (key.wheelDown) scrollDown()
+})
+```
+
+## useStdin
+
+Lower-level access to the stdin stream.
+
+```tsx
+import { useStdin } from '@anthropic/ink'
+
+const {
+  stdin,                    // Raw stdin stream
+  setRawMode,               // (enabled: boolean) => void
+  isRawModeSupported,       // boolean
+  internal_exitOnCtrlC,     // boolean
+  internal_eventEmitter,    // EventEmitter | undefined
+  internal_querier,         // Terminal querier
+} = useStdin()
+```
+
+> **Prefer `useInput` for keyboard handling.** `useStdin` is for advanced use cases like terminal querying or custom event handling.
+
+## Button Component
+
+Interactive button that responds to keyboard and mouse:
+
+```tsx
+import { Button } from '@anthropic/ink'
+
+<Button onAction={() => handleClick()} tabIndex={0} autoFocus>
+  {(state) => (
+    <Text bold={state.focused} color={state.focused ? 'claude' : 'text'}>
+      {state.focused ? '> Click Me' : '  Click Me'}
+    </Text>
+  )}
+</Button>
+```
+
+Button receives a render prop with state:
+
+```ts
+type ButtonState = {
+  focused: boolean    // Has keyboard focus
+  hovered: boolean    // Mouse is over it (alt-screen)
+  active: boolean     // True for 100ms after activation (flash effect)
+}
+```
+
+Activation triggers: Enter key, Space key, or mouse click.

packages/@ant/ink/docs/08-keybindings.md

@@ -0,0 +1,302 @@
+# Chapter 8: Keybinding System
+
+The keybinding system provides configurable, context-aware keyboard shortcuts with chord sequence support.
+
+## Architecture
+
+```
+KeybindingSetup (loads config)
+  └── KeybindingProvider (provides context)
+        ├── useKeybinding(action, handler)
+        ├── useKeybindings({ action: handler })
+        ├── useKeybindingContext()
+        └── useRegisterKeybindingContext(name, isActive)
+```
+
+## KeybindingSetup
+
+Loads and validates keybinding configuration at app startup.
+
+```tsx
+import { KeybindingSetup } from '@anthropic/ink'
+
+<KeybindingSetup
+  loadBindings={() => parseUserKeybindings(configFile)}
+  subscribeToChanges={(cb) => watchConfigFile(cb)}
+  onWarnings={(warnings, isReload) => {
+    warnings.forEach(w => console.warn(w.message))
+  }}
+>
+  <App />
+</KeybindingSetup>
+```
+
+### Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `children` | `ReactNode` | App tree |
+| `loadBindings` | `() => KeybindingsLoadResult` | Load bindings from config |
+| `subscribeToChanges` | `(cb) => unsubscribe` | Watch for config changes |
+| `initWatcher` | `() => void \| Promise<void>` | One-time setup (optional) |
+| `onWarnings` | `(warnings, isReload) => void` | Validation warnings (optional) |
+| `onDebugLog` | `(message) => void` | Debug logging (optional) |
+
+### KeybindingsLoadResult
+
+```ts
+type KeybindingsLoadResult = {
+  bindings: ParsedBinding[]
+  warnings: KeybindingWarning[]
+}
+```
+
+### KeybindingWarning
+
+```ts
+type KeybindingWarning = {
+  type: 'parse_error' | 'duplicate' | 'reserved' | 'invalid_context' | 'invalid_action'
+  severity: 'error' | 'warning'
+  message: string
+  key?: string
+  context?: string
+  action?: string
+  suggestion?: string
+}
+```
+
+## KeybindingProvider
+
+Context provider that holds binding state and resolution logic. Automatically provided by `KeybindingSetup`.
+
+## useKeybinding
+
+Register a handler for a keybinding action.
+
+```tsx
+import { useKeybinding } from '@anthropic/ink'
+
+function MyComponent() {
+  useKeybinding('app:toggleTodos', () => {
+    setShowTodos(prev => !prev)
+  }, { context: 'Global' })
+
+  // Return false to NOT consume the event (allow propagation)
+  useKeybinding('scroll:lineDown', () => {
+    if (!hasContent) return false  // Don't consume
+    scrollBy(1)
+  })
+}
+```
+
+### Signature
+
+```ts
+function useKeybinding(
+  action: string,
+  handler: () => void | false | Promise<void>,
+  options?: { context?: string; isActive?: boolean }
+): void
+```
+
+### Handler Return Values
+
+| Return | Effect |
+|--------|--------|
+| `undefined` / `void` | Event consumed, stop propagation |
+| `false` | Event NOT consumed, propagate to other handlers |
+| `Promise<void>` | Async handler, treated as consumed |
+
+## useKeybindings
+
+Register multiple handlers in one hook (reduces `useInput` overhead).
+
+```tsx
+import { useKeybindings } from '@anthropic/ink'
+
+useKeybindings({
+  'chat:submit': () => handleSubmit(),
+  'chat:cancel': () => handleCancel(),
+  'scroll:pageDown': () => {
+    scrollBy(viewportHeight)
+  },
+  'scroll:lineDown': () => {
+    if (!hasContent) return false
+    scrollBy(1)
+  },
+}, { context: 'Chat' })
+```
+
+## Keybinding Contexts
+
+Contexts allow the same key to perform different actions depending on what's active.
+
+```tsx
+// Register a context as active
+import { useRegisterKeybindingContext } from '@anthropic/ink'
+
+function ThemePicker({ isOpen }) {
+  useRegisterKeybindingContext('ThemePicker', isOpen)
+
+  // While open, 'ThemePicker' context bindings take precedence
+  useKeybinding('picker:select', handleSelect, { context: 'ThemePicker' })
+
+  return isOpen ? <PickerUI /> : null
+}
+```
+
+Context resolution order:
+1. Registered active contexts (most recent first)
+2. The hook's own `context` parameter
+3. `'Global'` (always checked last)
+
+## Chord Sequences
+
+Keybindings support multi-key sequences (chords):
+
+```
+"ctrl+k ctrl+s"  →  Save (press Ctrl+K, then Ctrl+S)
+"ctrl+k ctrl+c"  →  Close (press Ctrl+K, then Ctrl+C)
+```
+
+When a chord prefix is pressed:
+- `result.type === 'chord_started'` -- Show "Ctrl+K ..." pending indicator
+- Next key completes or cancels the chord
+- `result.type === 'chord_cancelled'` -- Invalid key, reset
+
+## KeybindingContext Hook
+
+```tsx
+import { useKeybindingContext, useOptionalKeybindingContext } from '@anthropic/ink'
+
+const ctx = useKeybindingContext()
+// ctx.resolve(input, key, contexts)  → ResolveResult
+// ctx.bindings                       → ParsedBinding[]
+// ctx.pendingChord                   → ParsedKeystroke[] | null
+// ctx.activeContexts                  → Set<string>
+// ctx.getDisplayText(action, context) → string | undefined
+// ctx.invokeAction(action)           → boolean
+// ctx.registerHandler(registration)   → () => void  (unsubscribe)
+
+// Returns null outside provider (no throw)
+const optionalCtx = useOptionalKeybindingContext()
+```
+
+## Parser Functions
+
+Parse and format keybinding strings:
+
+```tsx
+import {
+  parseKeystroke,
+  parseChord,
+  keystrokeToString,
+  chordToString,
+  keystrokeToDisplayString,
+  chordToDisplayString,
+  parseBindings,
+} from '@anthropic/ink'
+```
+
+### `parseKeystroke(str)`
+
+Parse a single keystroke string:
+
+```ts
+parseKeystroke('ctrl+shift+enter')
+// → { key: 'enter', ctrl: true, alt: false, shift: true, meta: false, super: false }
+```
+
+### `parseChord(str)`
+
+Parse a chord (space-separated keystrokes):
+
+```ts
+parseChord('ctrl+k ctrl+s')
+// → [{ key: 'k', ctrl: true, ... }, { key: 's', ctrl: true, ... }]
+```
+
+### `keystrokeToString(ks)` / `chordToString(chord)`
+
+Convert parsed keystroke/chord back to string.
+
+### `keystrokeToDisplayString(ks)` / `chordToDisplayString(chord)`
+
+Convert to human-readable display string (platform-aware).
+
+### `parseBindings(blocks)`
+
+Parse a keybinding configuration:
+
+```ts
+parseBindings([
+  {
+    context: 'Global',
+    bindings: {
+      'ctrl+s': 'app:save',
+      'ctrl+k ctrl+s': 'app:saveAs',
+    }
+  }
+])
+// → ParsedBinding[]
+```
+
+## Match Functions
+
+```tsx
+import { getKeyName, matchesKeystroke, matchesBinding } from '@anthropic/ink'
+```
+
+### `getKeyName(input, key)`
+
+Get the canonical key name from raw input:
+
+```ts
+getKeyName('\x1b[A', { upArrow: true })  // 'up'
+```
+
+### `matchesKeystroke(input, key, target)`
+
+Check if raw input matches a parsed keystroke:
+
+```ts
+matchesKeystroke('s', { ctrl: true, shift: false }, { key: 's', ctrl: true })
+```
+
+### `matchesBinding(input, key, binding)`
+
+Check if raw input matches any keystroke in a binding's chord.
+
+## Resolver Functions
+
+```tsx
+import { resolveKey, resolveKeyWithChordState, getBindingDisplayText } from '@anthropic/ink'
+```
+
+### `resolveKey(input, key, contexts, bindings)`
+
+Resolve input to a binding action:
+
+```ts
+const result = resolveKey('s', { ctrl: true, shift: false }, ['Global'], bindings)
+// result.type: 'match' | 'none' | 'unbound'
+// result.action: string (when type === 'match')
+```
+
+### `resolveKeyWithChordState(input, key, contexts, bindings, pendingChord)`
+
+Resolve with chord state:
+
+```ts
+const result = resolveKeyWithChordState('k', key, ['Global'], bindings, null)
+// result.type: 'match' | 'none' | 'unbound' | 'chord_started' | 'chord_cancelled'
+// result.pending: ParsedKeystroke[] (when type === 'chord_started')
+```
+
+### `getBindingDisplayText(action, context, bindings)`
+
+Get the display string for a binding:
+
+```ts
+getBindingDisplayText('app:save', 'Global', bindings)  // 'Ctrl+S'
+```

packages/@ant/ink/docs/09-hooks-reference.md

@@ -0,0 +1,407 @@
+# Chapter 9: Hooks Reference
+
+Complete API reference for all hooks exported by `@anthropic/ink`.
+
+---
+
+## Application Hooks
+
+### `useApp()`
+
+Access app-level operations.
+
+```ts
+function useApp(): {
+  exit: (error?: Error) => void
+}
+```
+
+Example:
+```tsx
+const { exit } = useApp()
+// Gracefully unmount and exit
+exit()
+```
+
+### `useStdin()`
+
+Access the stdin stream and raw mode control.
+
+```ts
+function useStdin(): {
+  stdin: NodeJS.ReadStream
+  isRawModeSupported: boolean
+  setRawMode: (enabled: boolean) => void
+  internal_exitOnCtrlC: boolean
+  internal_eventEmitter: EventEmitter | undefined
+  internal_querier: TerminalQuerier | null
+}
+```
+
+> Prefer `useInput` for keyboard handling.
+
+---
+
+## Input Hooks
+
+### `useInput(handler, options?)`
+
+Handle keyboard input. See [Chapter 7](./07-user-input.md) for full details.
+
+```ts
+function useInput(
+  handler: (input: string, key: Key, event: InputEvent) => void,
+  options?: { isActive?: boolean }
+): void
+```
+
+---
+
+## Terminal Hooks
+
+### `useTerminalSize()`
+
+Get current terminal dimensions.
+
+```ts
+function useTerminalSize(): {
+  columns: number
+  rows: number
+}
+```
+
+Throws if used outside `<App>`.
+
+### `useTerminalFocus()`
+
+Track whether the terminal window is focused.
+
+```ts
+function useTerminalFocus(): boolean
+```
+
+Uses DECSET 1004 focus reporting. Returns `true` when focused.
+
+### `useTerminalTitle(title)`
+
+Set the terminal window title.
+
+```ts
+function useTerminalTitle(title: string | null): void
+```
+
+Pass `null` to clear the title.
+
+### `useTerminalViewport()`
+
+Track element visibility in the terminal viewport.
+
+```ts
+function useTerminalViewport(): [
+  ref: (element: DOMElement | null) => void,
+  entry: { isVisible: boolean }
+]
+```
+
+Example:
+```tsx
+const [viewportRef, { isVisible }] = useTerminalViewport()
+
+<Box ref={viewportRef}>
+  <Text>{isVisible ? 'Visible' : 'Scrolled off'}</Text>
+</Box>
+```
+
+### `useTabStatus(kind)`
+
+Set tab status indicator in terminal tab bar (OSC 21337).
+
+```ts
+type TabStatusKind = 'idle' | 'busy' | 'waiting'
+function useTabStatus(kind: TabStatusKind | null): void
+```
+
+### `useTerminalNotification()`
+
+Send terminal notifications (iTerm2, Kitty, Ghostty, bell).
+
+```ts
+function useTerminalNotification(): {
+  notifyITerm2: (opts: { message: string; title?: string }) => void
+  notifyKitty: (opts: { message: string; title: string; id: number }) => void
+  notifyGhostty: (opts: { message: string; title: string }) => void
+  notifyBell: () => void
+  progress: (state: Progress['state'] | null, percentage?: number) => void
+}
+```
+
+Requires `TerminalWriteProvider` in the tree.
+
+Progress states: `'running'`, `'completed'`, `'error'`, `'indeterminate'`, `null` (clear).
+
+---
+
+## Animation & Timing Hooks
+
+### `useInterval(callback, intervalMs)`
+
+Clock-backed interval timer.
+
+```ts
+function useInterval(callback: () => void, intervalMs: number | null): void
+```
+
+Pass `null` to pause. Shares the application clock for efficient batching.
+
+### `useAnimationTimer(intervalMs)`
+
+Returns the current clock time, updating at the given interval.
+
+```ts
+function useAnimationTimer(intervalMs: number): number
+```
+
+Subscribes as non-keepAlive -- won't keep the clock running on its own.
+
+### `useAnimationFrame(intervalMs?)`
+
+Synchronized animation hook that pauses when offscreen.
+
+```ts
+function useAnimationFrame(
+  intervalMs?: number | null,  // default 16
+): [ref: (element: DOMElement | null) => void, time: number]
+```
+
+Returns a ref callback (attach to animated element) and the current animation time. All instances share the same clock. Pass `null` to pause.
+
+```tsx
+const [ref, time] = useAnimationFrame(120)
+const frame = Math.floor(time / 120) % FRAMES.length
+return <Box ref={ref}>{FRAMES[frame]}</Box>
+```
+
+### `useTimeout(delayMs, resetTrigger?)`
+
+One-shot timer.
+
+```ts
+function useTimeout(delay: number, resetTrigger?: number): boolean
+```
+
+Returns `true` when the timeout has elapsed. Change `resetTrigger` to restart.
+
+### `useMinDisplayTime(value, minMs)`
+
+Ensure a value is displayed for at least `minMs` milliseconds.
+
+```ts
+function useMinDisplayTime<T>(value: T, minMs: number): T
+```
+
+Holds the previous value until `minMs` has elapsed, then switches to the new value.
+
+Example:
+```tsx
+// Keep showing "Loading" for at least 300ms to prevent flash
+const displayValue = useMinDisplayTime(isLoading ? 'loading' : 'done', 300)
+```
+
+---
+
+## Interaction Hooks
+
+### `useDoublePress(setPending, onDoublePress, onFirstPress?)`
+
+Detect double-press (double-click equivalent for keyboard).
+
+```ts
+export const DOUBLE_PRESS_TIMEOUT_MS = 800
+
+function useDoublePress(
+  setPending: (pending: boolean) => void,
+  onDoublePress: () => void,
+  onFirstPress?: () => void
+): () => void  // Returns the press handler
+```
+
+Example:
+```tsx
+const [pendingExit, setPendingExit] = useState(false)
+const handlePress = useDoublePress(
+  setPendingExit,
+  () => exit(),       // Double press
+  () => {},           // First press
+)
+
+useInput((input, key) => {
+  if (key.escape) handlePress()
+})
+```
+
+### `useExitOnCtrlCD(options?)`
+
+Handle Ctrl+C / Ctrl+D with double-press confirmation.
+
+```ts
+type ExitState = {
+  pending: boolean
+  keyName: 'Ctrl-C' | 'Ctrl-D' | null
+}
+
+function useExitOnCtrlCDWithKeybindings(
+  onExit?: () => void,
+  onInterrupt?: () => boolean,
+  isActive?: boolean
+): ExitState
+```
+
+Example:
+```tsx
+const exitState = useExitOnCtrlCDWithKeybindings(
+  () => exit(),
+  () => { /* return true to prevent exit */ }
+)
+
+if (exitState.pending) {
+  return <Text>Press {exitState.keyName} again to exit</Text>
+}
+```
+
+---
+
+## Selection Hooks (Alt-Screen Only)
+
+### `useSelection()`
+
+Text selection operations.
+
+```ts
+function useSelection(): {
+  copySelection: () => string
+  copySelectionNoClear: () => string
+  clearSelection: () => void
+  hasSelection: () => boolean
+  getState: () => SelectionState | null
+  subscribe: (cb: () => void) => () => void
+  shiftAnchor: (dRow: number, minRow: number, maxRow: number) => void
+  shiftSelection: (dRow: number, minRow: number, maxRow: number) => void
+  moveFocus: (move: FocusMove) => void
+  captureScrolledRows: (firstRow: number, lastRow: number, side: 'above' | 'below') => void
+  setSelectionBgColor: (color: string) => void
+}
+```
+
+### `useHasSelection()`
+
+Reactive boolean for selection state.
+
+```ts
+function useHasSelection(): boolean
+```
+
+Re-renders when selection is created or cleared.
+
+---
+
+## Search Hooks
+
+### `useSearchHighlight()`
+
+Set and manage search highlighting.
+
+```ts
+function useSearchHighlight(): {
+  setQuery: (query: string) => void
+  scanElement: (el: DOMElement) => MatchPosition[]
+  setPositions: (state: { positions: MatchPosition[]; rowOffset: number; currentIdx: number } | null) => void
+}
+```
+
+### `useSearchInput(options)`
+
+Search input handler with cursor management.
+
+```ts
+type UseSearchInputOptions = {
+  isActive: boolean
+  onExit: () => void
+  onCancel?: () => void
+  onExitUp?: () => void
+  columns?: number
+  passthroughCtrlKeys?: string[]
+  initialQuery?: string
+  backspaceExitsOnEmpty?: boolean
+}
+
+type UseSearchInputReturn = {
+  query: string
+  setQuery: (q: string) => void
+  cursorOffset: number
+  handleKeyDown: (e: KeyboardEvent) => void
+}
+
+function useSearchInput(options: UseSearchInputOptions): UseSearchInputReturn
+```
+
+---
+
+## Cursor Hooks
+
+### `useDeclaredCursor(options)`
+
+Park the terminal cursor at a specific position for IME and accessibility.
+
+```ts
+function useDeclaredCursor({
+  line: number,
+  column: number,
+  active: boolean
+}): (element: DOMElement | null) => void
+```
+
+Returns a ref callback. Position is relative to the ref'd element.
+
+Example:
+```tsx
+const cursorRef = useDeclaredCursor({
+  line: 0,
+  column: cursorPosition,
+  active: isFocused,
+})
+
+return <Box ref={cursorRef}>...</Box>
+```
+
+---
+
+## Tab Status Hooks
+
+### `useTabStatus(kind)`
+
+Set tab status indicator (OSC 21337) for terminal tab bars.
+
+```ts
+type TabStatusKind = 'idle' | 'busy' | 'waiting'
+
+function useTabStatus(kind: TabStatusKind | null): void
+```
+
+Pass `null` to clear.
+
+---
+
+## Viewport Hooks
+
+### `useTerminalViewport()`
+
+Track element visibility within the terminal viewport.
+
+```ts
+function useTerminalViewport(): [
+  ref: (element: DOMElement | null) => void,
+  entry: { isVisible: boolean }
+]
+```
+
+Returns a ref callback and visibility state.

packages/@ant/ink/docs/10-events-and-focus.md

@@ -0,0 +1,232 @@
+# Chapter 10: Events & Focus
+
+## Event System
+
+Ink implements a DOM-like event system with capture/bubble phases, propagation control, and prioritized dispatch.
+
+### Event Classes
+
+All events extend the base `Event` class:
+
+```ts
+class Event {
+  stopImmediatePropagation(): void
+}
+```
+
+### InputEvent
+
+Emitted for every keystroke or input action.
+
+```ts
+class InputEvent extends Event {
+  readonly input: string     // Character(s) entered
+  readonly key: Key          // Parsed key metadata
+  readonly keypress: ParsedKey  // Raw keypress data
+}
+```
+
+### KeyboardEvent
+
+DOM-like keyboard event for focused elements.
+
+```ts
+class KeyboardEvent extends Event {
+  readonly key: Key
+}
+```
+
+Dispatched via `onKeyDown` / `onKeyDownCapture` on `Box`.
+
+### ClickEvent
+
+Mouse click event (alt-screen only).
+
+```ts
+class ClickEvent extends Event {
+  readonly x: number  // Column (0-indexed)
+  readonly y: number  // Row (0-indexed)
+}
+```
+
+Clicks bubble from the deepest hit Box up through ancestors.
+
+### FocusEvent
+
+Focus change event.
+
+```ts
+class FocusEvent extends Event {
+  readonly relatedTarget: DOMElement | null
+}
+```
+
+### TerminalFocusEvent
+
+Terminal window focus change.
+
+```ts
+class TerminalFocusEvent extends Event {
+  readonly type: 'terminalfocus' | 'terminalblur'
+}
+```
+
+### ResizeEvent
+
+Terminal resize event (internal).
+
+### PasteEvent
+
+Pasted text event (bracketed paste mode).
+
+## Event Dispatch Flow
+
+```
+stdin data → parse-keypress → InputEvent
+                                    ↓
+                    App.handleInput (useInput handlers)
+                                    ↓
+                    Box.onKeyDown (focused element, bubble)
+```
+
+### Capture and Bubble Phases
+
+```tsx
+<Box
+  onKeyDownCapture={(e) => {
+    // Capture phase: fires top-down
+    console.log('Parent captures key')
+  }}
+  onKeyDown={(e) => {
+    // Bubble phase: fires bottom-up
+    console.log('Parent receives bubbled key')
+  }}
+>
+  <Box
+    onKeyDown={(e) => {
+      // Target: fires first in bubble phase
+      console.log('Child handles key')
+      e.stopImmediatePropagation()  // Stop here
+    }}
+  >
+    <Text>Focus here</Text>
+  </Box>
+</Box>
+```
+
+### Event Propagation Methods
+
+| Method | Effect |
+|--------|--------|
+| `event.stopImmediatePropagation()` | Stop all subsequent handlers |
+| `event.preventDefault()` | Not supported in terminal context |
+
+## FocusManager
+
+DOM-like focus management system.
+
+### How Focus Works
+
+1. Elements with `tabIndex >= 0` participate in Tab/Shift+Tab cycling
+2. Elements with `tabIndex === -1` are programmatically focusable only
+3. Elements with `autoFocus` receive focus on mount
+4. Clicking a focusable element focuses it
+
+### Focus API
+
+```ts
+class FocusManager {
+  activeElement: DOMElement | null
+
+  focus(node: DOMElement): void
+  blur(): void
+  focusNext(root: DOMElement): void     // Tab
+  focusPrevious(root: DOMElement): void  // Shift+Tab
+
+  handleNodeRemoved(node: DOMElement, root: DOMElement): void
+  handleAutoFocus(node: DOMElement): void
+  handleClickFocus(node: DOMElement): void
+
+  enable(): void
+  disable(): void
+}
+```
+
+### Tab Navigation
+
+```tsx
+<Box flexDirection="column">
+  <Button tabIndex={0} onAction={handleSave}>
+    {(s) => <Text>{s.focused ? '> Save' : '  Save'}</Text>}
+  </Button>
+  <Button tabIndex={0} onAction={handleCancel}>
+    {(s) => <Text>{s.focused ? '> Cancel' : '  Cancel'}</Text>}
+  </Button>
+  <Button tabIndex={-1} onAction={handleSecret}>
+    {/* Not reachable via Tab */}
+    {(s) => <Text>Secret</Text>}
+  </Button>
+</Box>
+```
+
+### Auto Focus
+
+```tsx
+<Box tabIndex={0} autoFocus onKeyDown={handleKey}>
+  <Text>Receives focus immediately on mount</Text>
+</Box>
+```
+
+### Focus Events
+
+```tsx
+<Box
+  tabIndex={0}
+  onFocus={(e) => console.log('Got focus')}
+  onBlur={(e) => console.log('Lost focus')}
+  onFocusCapture={(e) => console.log('Capture: focus in')}
+  onBlurCapture={(e) => console.log('Capture: focus out')}
+>
+  <Text>Focusable element</Text>
+</Box>
+```
+
+## Hit Testing
+
+Mouse click/hover resolution:
+
+1. Screen coordinates are mapped to DOM elements via Yoga layout
+2. The deepest element at the click position is the target
+3. Click events bubble upward through ancestors
+4. Hover events use `mouseenter`/`mouseleave` semantics (no bubbling between children)
+
+### Click Hit Testing
+
+```ts
+dispatchClick(rootNode, col, row): void
+```
+
+Walks the DOM tree, finds the deepest Box at (col, row), fires `onClick`, then bubbles to ancestors.
+
+### Hover Hit Testing
+
+```ts
+dispatchHover(rootNode, col, row, hoveredNodes): void
+```
+
+Tracks which nodes are under the pointer. Fires `onMouseEnter`/`onMouseLeave` as the pointer moves between elements.
+
+## EventEmitter
+
+Custom event emitter for internal use:
+
+```ts
+class EventEmitter {
+  on(event: string, handler: Function): void
+  off(event: string, handler: Function): void
+  emit(event: string, ...args: any[]): void
+  removeListener(event: string, handler: Function): void
+}
+```
+
+Used internally by the Ink instance for `input` events.

packages/@ant/ink/docs/11-core-architecture.md

@@ -0,0 +1,301 @@
+# Chapter 11: Core Architecture
+
+This chapter covers the internal rendering pipeline, DOM model, and screen buffer system. This is advanced material -- most users only need the component and hooks APIs.
+
+## Rendering Pipeline
+
+```
+React Component Tree
+        ↓ (React reconciler)
+Ink DOM Tree (virtual terminal DOM)
+        ↓ (Yoga layout)
+Positioned DOM Tree (computed x, y, width, height)
+        ↓ (renderNodeToOutput)
+Output Buffer (styled characters)
+        ↓ (renderer → Screen)
+Screen Buffer (Int32Array of cells)
+        ↓ (diffEach)
+ANSI Diff Patches (minimal escape sequences)
+        ↓ (writeDiffToTerminal)
+Terminal stdout
+```
+
+### Frame Lifecycle
+
+Each render cycle (`onRender`) follows these phases:
+
+1. **React Commit** -- React reconciles the virtual tree; host config updates Ink DOM
+2. **Yoga Layout** -- All dirty nodes have their styles applied and layout computed
+3. **Renderer** -- Creates Output buffer, calls `renderNodeToOutput` for the full tree
+4. **Screen Diff** -- New frame is compared against previous frame cell-by-cell
+5. **Optimize** -- Patches are merged and ordered for minimal cursor movement
+6. **Write** -- ANSI escape sequences are written to stdout
+
+### Frame Timing
+
+```ts
+const FRAME_INTERVAL_MS = 16  // ~60fps cap
+```
+
+Renders are throttled. Multiple state updates in one frame are batched.
+
+### Double Buffering
+
+Two frames are maintained:
+
+- **`frontFrame`** -- The currently displayed frame
+- **`backFrame`** -- The frame being rendered
+
+After rendering, they are swapped. This prevents partial updates from being visible.
+
+## Ink DOM
+
+### Node Types
+
+```ts
+type ElementNames =
+  | 'ink-root'        // Root container
+  | 'ink-box'         // Box component
+  | 'ink-text'        // Text component
+  | 'ink-virtual-text' // Intermediate text wrapper
+  | 'ink-link'        // Link component
+  | 'ink-raw-ansi'    // Raw ANSI content
+```
+
+### DOMElement
+
+```ts
+type DOMElement = {
+  nodeName: ElementNames
+  attributes: Record<string, unknown>
+  childNodes: DOMNode[]      // DOMElement | TextNode
+  yogaNode?: LayoutNode      // Yoga layout node
+  textStyles?: TextStyles    // Inherited text styles
+
+  // Scroll state
+  scrollTop?: number
+  scrollHeight?: number
+  scrollViewportHeight?: number
+  scrollViewportTop?: number
+  stickyScroll?: boolean
+  pendingScrollDelta?: number
+  scrollAnchor?: { el: DOMElement; offset: number }
+
+  // Dirty tracking
+  dirty: boolean
+
+  // Event handlers (stored separately)
+  onClick?: (event: ClickEvent) => void
+  onFocus?: (event: FocusEvent) => void
+  onBlur?: (event: FocusEvent) => void
+  onKeyDown?: (event: KeyboardEvent) => void
+  onMouseEnter?: () => void
+  onMouseLeave?: () => void
+}
+```
+
+### TextNode
+
+```ts
+type TextNode = {
+  nodeName: '#text'
+  nodeValue: string
+  yogaNode?: LayoutNode
+}
+```
+
+### DOM Operations
+
+```ts
+// Node creation
+createNode(nodeName: string): DOMElement
+createTextNode(text: string): TextNode
+
+// Tree manipulation
+appendChildNode(parent: DOMElement, child: DOMNode): void
+insertBeforeNode(parent: DOMElement, child: DOMNode, before: DOMNode): void
+removeChildNode(parent: DOMElement, child: DOMNode): void
+
+// Attribute manipulation
+setAttribute(node: DOMElement, key: string, value: unknown): void
+setStyle(node: DOMElement, style: Styles): void
+setTextStyles(node: DOMElement, styles: TextStyles): void
+
+// Dirty tracking
+markDirty(node: DOMElement): void
+scheduleRenderFrom(node: DOMElement): void
+```
+
+## Screen Buffer
+
+### Cell Storage
+
+The screen buffer uses packed `Int32Array` storage for memory efficiency:
+
+```ts
+type Screen = {
+  width: number
+  height: number
+  cells: Int32Array        // 2 Int32s per cell: [charId, packed_style_hyperlink_width]
+  cells64: BigInt64Array   // For bulk fill operations
+  charPool: CharPool       // String interning
+  stylePool: StylePool     // ANSI code interning
+  hyperlinkPool: HyperlinkPool
+  emptyStyleId: number
+  damage: Rectangle | undefined  // Bounding box of changed cells
+  noSelect: Uint8Array     // Per-cell no-select bitmap
+  softWrap: Int32Array     // Per-row soft-wrap markers
+}
+```
+
+### Cell Width
+
+```ts
+enum CellWidth {
+  Narrow = 0,       // Regular character (1 column)
+  Wide = 1,         // CJK/emoji (2 columns)
+  SpacerTail = 2,   // Right half of wide character
+  SpacerHead = 3,   // Soft-wrapped wide character
+}
+```
+
+### Style Pool
+
+ANSI style codes are interned for efficiency:
+
+```ts
+class StylePool {
+  intern(codes: AnsiCode[]): number    // Returns compact ID
+  get(id: number): AnsiCode[]
+  transition(from: number, to: number): string  // Cached ANSI transition
+  withInverse(id: number): number     // Selection overlay
+  setSelectionBg(bg: AnsiCode): void  // Theme-aware selection bg
+}
+```
+
+### Diff Algorithm
+
+```ts
+diffEach(prev: Screen, next: Screen, callback: (x, y, oldCell, newCell) => void): void
+```
+
+Only iterates cells within the damage bounding box. Unchanged regions are skipped entirely.
+
+### Screen Operations
+
+```ts
+createScreen(width, height, stylePool, charPool, hyperlinkPool): Screen
+setCellAt(screen, x, y, cell): void
+cellAt(screen, x, y): Cell
+clearRegion(screen, x, y, width, height): void
+blitRegion(dst, src, x, y, maxX, maxY): void
+shiftRows(screen, top, bottom, n): void
+```
+
+## Layout Engine
+
+### Yoga Integration
+
+Ink wraps Facebook's Yoga layout engine for Flexbox computation:
+
+```ts
+// Layout node types
+enum LayoutDisplay { Flex, None }
+enum LayoutPositionType { Absolute, Relative }
+enum LayoutOverflow { Visible, Hidden, Scroll }
+enum LayoutFlexDirection { Row, Column, RowReverse, ColumnReverse }
+enum LayoutWrap { NoWrap, Wrap, WrapReverse }
+enum LayoutAlign { FlexStart, Center, FlexEnd, Stretch }
+enum LayoutJustify { FlexStart, Center, FlexEnd, SpaceBetween, SpaceAround, SpaceEvenly }
+enum LayoutEdge { Top, Bottom, Left, Right, Start, End, Horizontal, Vertical, All }
+enum LayoutGutter { Column, Row, All }
+```
+
+### Style Application
+
+Styles from React props are applied to Yoga nodes during the commit phase:
+
+```ts
+function styles(node: LayoutNode, style: Styles, resolvedStyle?: Styles): void
+```
+
+This function maps each CSS-like prop to the corresponding Yoga setter.
+
+## Output Buffer
+
+Intermediate rendering target before screen diff:
+
+```ts
+class Output {
+  write(text: string, x: number, y: number, styles: TextStyles): void
+  wrap(width: number, textWrap: TextWrap): void
+}
+```
+
+`renderNodeToOutput` walks the DOM tree and writes styled characters into this buffer.
+
+## Reconciler
+
+Custom React reconciler that bridges React and the Ink DOM:
+
+- **Host config** -- Defines how React operations map to Ink DOM mutations
+- **Concurrent mode** -- Supports `ConcurrentRoot` for React 19 features
+- **Yoga integration** -- Applies styles during commit phase
+- **DevTools** -- Connected in development mode
+
+### Host Config Methods
+
+| Method | Purpose |
+|--------|---------|
+| `createInstance` | Create `ink-box`, `ink-text`, etc. |
+| `createTextInstance` | Create `#text` node |
+| `appendChildNode` | Add child to parent |
+| `removeChildNode` | Remove child from parent |
+| `insertBefore` | Insert child before sibling |
+| `commitUpdate` | Update element attributes/styles |
+| `commitTextUpdate` | Update text content |
+| `getPublicInstance` | Return DOMElement for refs |
+
+## Performance Optimizations
+
+1. **String Interning** -- CharPool deduplicates character strings across frames
+2. **Style Caching** -- StylePool caches ANSI transition strings
+3. **Damage Tracking** -- Only diff cells within the changed bounding box
+4. **Bulk Operations** -- `Int32Array.set()` for fast region blit
+5. **Throttled Rendering** -- Frame rate capped at ~60fps
+6. **Viewport Culling** -- ScrollBox only renders visible children
+7. **Microtask Coalescing** -- Multiple scroll deltas merged into one render
+
+## Frame Events
+
+Debug instrumentation for render performance:
+
+```ts
+type FrameEvent = {
+  durationMs: number
+  phases: {
+    renderer: number    // Yoga + renderNodeToOutput
+    diff: number        // Screen diff
+    optimize: number    // Patch optimization
+    write: number       // Terminal write
+    patches: number     // Number of ANSI patches
+    yoga: number        // Yoga layout time
+    commit: number      // React commit time
+    yogaVisited: number // Yoga nodes visited
+    yogaMeasured: number // Yoga nodes measured
+    yogaCacheHits: number // Cached measurements
+    yogaLive: number    // Active Yoga nodes
+  }
+  flickers: FlickerReason[]
+}
+```
+
+Enable with `onFrame` in RenderOptions:
+
+```tsx
+render(<App />, {
+  onFrame: (event) => {
+    console.log(`Frame: ${event.durationMs}ms`)
+  }
+})
+```

packages/@ant/ink/docs/12-terminal-integration.md

@@ -0,0 +1,381 @@
+# Chapter 12: Terminal Integration
+
+This chapter covers terminal-specific features: alternate screen, mouse tracking, clipboard, notifications, and terminal querying.
+
+## Alternate Screen
+
+Enter a fullscreen alternate screen buffer (like vim, less, htop).
+
+```tsx
+import { AlternateScreen } from '@anthropic/ink'
+
+<AlternateScreen mouseTracking={true}>
+  <Box flexDirection="column" height="100%">
+    <Text>Fullscreen content</Text>
+  </Box>
+</AlternateScreen>
+```
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `ReactNode` | - | Content |
+| `mouseTracking` | `boolean` | `true` | Enable SGR mouse tracking |
+
+### Behavior
+
+On mount:
+1. Enters DEC 1049 alternate screen buffer
+2. Hides cursor
+3. Enables mouse tracking (if `mouseTracking=true`)
+4. Constrains rendering height to terminal rows
+
+On unmount:
+1. Exits alternate screen buffer
+2. Shows cursor
+3. Disables mouse tracking
+4. Restores original terminal content
+
+### Mouse Tracking Modes
+
+When enabled:
+- **Mode 1003** -- Button press/release + motion (hover)
+- **Mode 1006** -- SGR extended mouse format (coordinates > 223)
+- **Wheel events** -- Scroll up/down
+
+### External Editor Handoff
+
+The Ink instance supports pausing for an external editor:
+
+```ts
+// Pause Ink, run external command, resume
+ink.enterAlternateScreen()  // Save state
+// ... external editor runs ...
+ink.reassertTerminalModes()  // Restore on resume
+```
+
+This is triggered by Ctrl+Z (SIGTSTP) and SIGCONT.
+
+## Mouse Events
+
+### Click Events
+
+```tsx
+<Box onClick={(event) => {
+  console.log(`Clicked at col=${event.x}, row=${event.y}`)
+  event.stopImmediatePropagation()
+}}>
+  <Text>Clickable area</Text>
+</Box>
+```
+
+### Multi-Click
+
+Double-click selects a word, triple-click selects a line. Handled by the App component:
+
+```ts
+// App prop
+onMultiClick: (col: number, row: number, count: 2 | 3) => void
+```
+
+### Hover Events
+
+```tsx
+<Box
+  onMouseEnter={() => setHovered(true)}
+  onMouseLeave={() => setHovered(false)}
+>
+  <Text>{hovered ? 'Hovered!' : 'Hover me'}</Text>
+</Box>
+```
+
+Hover uses `mouseenter`/`mouseleave` semantics (no bubbling between children).
+
+### Drag-to-Select
+
+In alt-screen mode, click-drag creates a text selection:
+
+```ts
+// App prop
+onSelectionDrag: (col: number, row: number) => void
+```
+
+## Clipboard
+
+### OSC 52 Clipboard
+
+```tsx
+import { setClipboard } from '@anthropic/ink'
+
+await setClipboard('Copied text')
+```
+
+### Copy Selection
+
+```tsx
+const { copySelection } = useSelection()
+const text = copySelection()  // Copies to clipboard and clears highlight
+```
+
+### Copy Without Clear
+
+```tsx
+const { copySelectionNoClear } = useSelection()
+const text = copySelectionNoClear()  // Copies but keeps highlight
+```
+
+## Terminal Notifications
+
+Send desktop notifications from the terminal.
+
+```tsx
+import { useTerminalNotification } from '@anthropic/ink'
+
+function MyComponent() {
+  const { notifyBell, progress } = useTerminalNotification()
+
+  // Terminal bell (audible/system notification)
+  notifyBell()
+
+  // Progress bar in terminal title/tab
+  progress('running', 65)    // 65% complete
+  progress('completed')       // Done
+  progress('error')           // Error state
+  progress('indeterminate')   // Unknown progress
+  progress(null)              // Clear
+}
+```
+
+### Terminal-Specific Notifications
+
+```tsx
+const { notifyITerm2, notifyKitty, notifyGhostty } = useTerminalNotification()
+
+// iTerm2
+notifyITerm2({ message: 'Build complete', title: 'My App' })
+
+// Kitty
+notifyKitty({ message: 'Build complete', title: 'My App', id: 1 })
+
+// Ghostty
+notifyGhostty({ message: 'Build complete', title: 'My App' })
+```
+
+## Terminal Queries
+
+### Background Color (OSC 11)
+
+Used for auto-theme detection:
+
+```ts
+import { getTerminalBackground } from '@anthropic/ink'
+const bg = await getTerminalBackground()
+// e.g., 'rgb:0000/0000/0000' (dark) or 'rgb:ffff/ffff/ffff' (light)
+```
+
+### Terminal Version (XTVERSION)
+
+```ts
+import { isXtermJs, setXtversionName, getXtversionName } from '@anthropic/ink'
+```
+
+### Feature Detection
+
+```ts
+import { supportsHyperlinks } from '@anthropic/ink'
+
+if (supportsHyperlinks()) {
+  // OSC 8 hyperlinks supported
+}
+
+import { supportsExtendedKeys } from '@anthropic/ink'
+
+if (supportsExtendedKeys()) {
+  // Kitty keyboard protocol / modifyOtherKeys available
+}
+```
+
+## Terminal Focus
+
+Track terminal window focus/unfocus:
+
+```tsx
+import { useTerminalFocus } from '@anthropic/ink'
+
+const isFocused = useTerminalFocus()
+```
+
+Low-level API:
+
+```ts
+import { getTerminalFocused, subscribeTerminalFocus } from '@anthropic/ink'
+
+getTerminalFocused()  // boolean
+subscribeTerminalFocus((focused: boolean) => {
+  // Called on focus change
+})
+```
+
+Uses DECSET 1004 focus reporting.
+
+## Terminal Title
+
+Set the terminal window title:
+
+```tsx
+import { useTerminalTitle } from '@anthropic/ink'
+
+useTerminalTitle('My App - Dashboard')
+```
+
+Clear:
+
+```tsx
+useTerminalTitle(null)
+```
+
+## Terminal I/O Sequences
+
+Low-level ANSI sequence constants for advanced use.
+
+### Cursor Control
+
+```ts
+import {
+  SHOW_CURSOR,
+  HIDE_CURSOR,
+  CURSOR_HOME,
+} from '@anthropic/ink'
+
+// cursorPosition(row, col) -- Move cursor to absolute position
+// cursorMove(dx, dy) -- Move cursor relative
+```
+
+### Screen Control
+
+```ts
+import {
+  ENTER_ALT_SCREEN,
+  EXIT_ALT_SCREEN,
+  ERASE_SCREEN,
+} from '@anthropic/ink'
+```
+
+### Mouse Control
+
+```ts
+import {
+  ENABLE_MOUSE_TRACKING,
+  DISABLE_MOUSE_TRACKING,
+} from '@anthropic/ink'
+```
+
+### Keyboard Protocols
+
+```ts
+import {
+  ENABLE_KITTY_KEYBOARD,
+  DISABLE_KITTY_KEYBOARD,
+  ENABLE_MODIFY_OTHER_KEYS,
+  DISABLE_MODIFY_OTHER_KEYS,
+} from '@anthropic/ink'
+```
+
+### Clipboard & Tab Status
+
+```ts
+import {
+  CLEAR_ITERM2_PROGRESS,
+  CLEAR_TAB_STATUS,
+  CLEAR_TERMINAL_TITLE,
+  wrapForMultiplexer,
+} from '@anthropic/ink'
+```
+
+`wrapForMultiplexer` wraps OSC sequences for tmux compatibility.
+
+## Terminal Compatibility
+
+### Supported Terminals
+
+| Terminal | Features |
+|----------|----------|
+| iTerm2 | Full support (hyperlinks, notifications, progress) |
+| Kitty | Full support (keyboard protocol, notifications) |
+| Ghostty | Full support |
+| WezTerm | Full support |
+| Alacritty | Most features |
+| Windows Terminal | Most features |
+| Apple Terminal | 256-color fallback |
+| xterm.js (VS Code) | Detected and special-cased |
+| tmux | Wrapped sequences via `wrapForMultiplexer` |
+| Screen | Basic support |
+
+### Feature Degradation
+
+The framework gracefully degrades:
+- No true color → Falls back to ANSI 16-color themes
+- No OSC 52 → Clipboard operations silently fail
+- No mouse tracking → Click/hover events are no-ops
+- No extended keys → Standard escape sequences used
+- No bracketed paste → Paste detected by timing heuristic
+
+### Synchronized Output
+
+```ts
+import { isSynchronizedOutputSupported } from '@anthropic/ink'
+
+if (isSynchronizedOutputSupported()) {
+  // BSU/ESU for tear-free rendering
+}
+```
+
+Uses DECSET 2026 synchronized output to prevent partial frame display.
+
+### Bracketed Paste
+
+Uses DECSET 2004 to distinguish paste events from rapid typing. Automatically enabled by the App component.
+
+## Text Selection (Alt-Screen)
+
+### Selection State
+
+```ts
+type SelectionState = {
+  anchor: Point | null        // Drag start
+  focus: Point | null         // Current position
+  isDragging: boolean
+  anchorSpan: { lo: Point; hi: Point; kind: 'word' | 'line' } | null
+  scrolledOffAbove: string[]  // Text scrolled out above
+  scrolledOffBelow: string[]  // Text scrolled out below
+}
+```
+
+### Selection Operations
+
+- **Click-drag** -- Free-form selection
+- **Double-click** -- Word selection
+- **Triple-click** -- Line selection
+- **Shift+Arrow** -- Extend selection from keyboard
+- **Drag-to-scroll** -- Auto-scroll when dragging near edges
+
+### noSelect Regions
+
+Exclude areas from selection (gutters, line numbers):
+
+```tsx
+<Box noSelect={true}>
+  <Text>1 │</Text>
+</Box>
+<Box>
+  <Text>code here</Text>  {/* Only this is selectable */}
+</Box>
+```
+
+### Soft-Wrap Awareness
+
+Selection correctly handles text that was wrapped across multiple rows:
+- Wrapped lines are joined when copied
+- Trailing whitespace is trimmed
+- The `softWrap` bitmap tracks which rows are continuations

packages/@ant/ink/docs/README.md

@@ -0,0 +1,46 @@
+# @anthropic/ink Documentation
+
+A terminal React rendering framework for building rich command-line interfaces.
+
+## Architecture Overview
+
+`@anthropic/ink` is a forked/internal Ink framework that renders React components directly to the terminal using ANSI escape sequences. It uses Yoga (via a custom layout engine) for Flexbox layout, a custom React reconciler for terminal DOM, and a screen-buffer differ for efficient updates.
+
+### Three-Layer Architecture
+
+```
+┌─────────────────────────────────────────┐
+│  Layer 3: Theme                         │
+│  ThemeProvider, ThemedBox, ThemedText,  │
+│  Dialog, FuzzyPicker, ProgressBar, etc. │
+├─────────────────────────────────────────┤
+│  Layer 2: Components                    │
+│  Box, Text, ScrollBox, Button, Link,    │
+│  Newline, Spacer, AlternateScreen       │
+├─────────────────────────────────────────┤
+│  Layer 1: Core                          │
+│  Reconciler, Layout (Yoga), Terminal    │
+│  I/O, Screen Buffer, Event System       │
+└─────────────────────────────────────────┘
+```
+
+- **Core** (`src/core/`) -- Rendering engine: React reconciler, Yoga flexbox layout, terminal I/O, screen buffer with diff-based updates, event system (keyboard, mouse, focus, click).
+- **Components** (`src/components/`) -- UI primitives: `Box`, `Text`, `ScrollBox`, `Button`, `Link`, `Newline`, `Spacer`, etc. Plus context providers (`App`, `StdinContext`).
+- **Theme** (`src/theme/`) -- Theme system: `ThemeProvider`, theme-aware `Box`/`Text` wrappers, and design-system components (`Dialog`, `FuzzyPicker`, `ProgressBar`, `Tabs`, etc.).
+
+### Documentation
+
+| Chapter | File | Contents |
+|---------|------|----------|
+| 1 | [Getting Started](./01-getting-started.md) | Installation, rendering, basic concepts |
+| 2 | [Layout System](./02-layout.md) | Box, Flexbox, Yoga, positioning, dimensions |
+| 3 | [Text & Styling](./03-text-and-styling.md) | Text component, colors, text wrapping, ANSI styling |
+| 4 | [Theme System](./04-theme-system.md) | ThemeProvider, themes, ThemedBox, ThemedText, color() |
+| 5 | [Design System Components](./05-design-system.md) | Dialog, ProgressBar, FuzzyPicker, Tabs, Spinner, etc. |
+| 6 | [Scrolling](./06-scrolling.md) | ScrollBox, sticky scroll, imperative scroll API |
+| 7 | [User Input](./07-user-input.md) | useInput, Key types, raw mode, mouse events |
+| 8 | [Keybinding System](./08-keybindings.md) | KeybindingProvider, useKeybinding, chord sequences, parser |
+| 9 | [Hooks Reference](./09-hooks-reference.md) | All hooks with full API signatures |
+| 10 | [Events & Focus](./10-events-and-focus.md) | Event system, FocusManager, click/hover, tab navigation |
+| 11 | [Core Architecture](./11-core-architecture.md) | Reconciler, screen buffer, terminal I/O, rendering pipeline |
+| 12 | [Terminal Integration](./12-terminal-integration.md) | Alternate screen, mouse tracking, clipboard, notifications |